Понимание базового ответа на проверку адреса

Ответ API проверки адреса содержит следующие свойства верхнего уровня:

{
  // Address details determined by the API.
  "address": {},
  // Validation verdict.
  "verdict": {},
  // The geocode generated for the input address.
  "geocode": {},
  // Information indicating if the address is a business, residence, etc.
  "metadata": {},
  // Information about the address from the US Postal Service
  // ("US" and "PR" addresses only).
  "uspsData": {},
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

verdict собственности

Свойство verdict суммирует результаты проверки адреса и должно быть первым свойством, которое следует оценивать при построении логики проверки адреса. Это свойство может возвращать различные поля в зависимости от качества выходного адреса. Например, ниже показано свойство verdict для адреса хорошего качества, которое возвращает следующие поля для данного запроса:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "possibleNextAction": "ACCEPT",
  "addressComplete": true,
  "hasUnconfirmedComponents": false,
  "hasInferredComponents": true,
  "hasReplacedComponents": false
}

В следующих разделах обобщены все поля в свойстве verdict .

Детализация адреса

Детализация адреса — это уровень детализации, используемый для определения специфичности адреса или геокода. Детализация адреса в ответе validationGranularity — ключевой сигнал, определяющий возмо��ность доставки адреса.

Свойство verdict возвращает следующие сигналы детализации:

• inputGranularity — описывает уровень детализации, полученный из адреса, отправленного на проверку адреса в Maps JavaScript API. Уровень детализации адреса в запросе влияет на уровень детализации адреса в ответе на проверку. Например, адрес с inputGranularity ниже уровня PREMISE ниже уровня обычно не приводит к уровню validationGranularity до уровня PREMISE .
• validationGranularity — уровень детализации, с которым функция проверки адреса в Maps JavaScript API может полностью проверить адрес. В большинстве случаев уровень детализации PREMISE или SUB_PREMISE указывает на качественный адрес, который, скорее всего, можно будет доставить.
• geocodeGranularity — описывает уровень детализации геокода, связанного с адресом. Например, записи Google могут указывать на наличие номера квартиры, но не на точное местоположение этой квартиры в крупном жилом комплексе. В этом случае значение validationGranularity равно SUB_PREMISE , а значение geocodeGranularity — PREMISE .

Полнота адреса

Вердикт возвращает свойство addressComplete как сигнал для высококачественного адреса, что означает, в частности, что в нем нет отсутствующих, неразрешенных или неожиданных компонентов:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true
}

Если в адресе имеются отсутствующие, неразрешенные или непредвиденные компоненты, полю присваивается значение false .

Качество адреса

Ряд возможных полей указывает либо на проблемы с компонентами адреса, либо на необходимость их корректировки, например, на предполагаемые или отсутствующие компоненты адреса. Например, следующее свойство verdict указывает на адрес с неподтверждёнными компонентами и отсутствующим полем addressComplete :

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

Возможные следующие действия

Поле вердикта possibleNextAction содержит краткое пояснение ответа API, призванное помочь определить возможные последующие действия. Это поле формируется на основе других полей ответа API и не должно рассматриваться как гарантия точности адреса или возможности доставки.

Свойства address и addressComponent

Свойство address обеспечивает форматирование обработанного адреса, предоставленного в запросе, а также сводки адреса на уровне компонентов, включая неправильно написанные части адреса, замененные неверные части и предполагаемые отсутствующие части.

Свойство addressComponent — это подкомпонент address , который содержит подробный список элементов (или компонентов) адреса, обработанных API проверки адреса в Maps JavaScript. API идентифицирует каждое поле компонента по его имени, типу и уровню подтверждения.

Свойство geocode

Свойство geocode указывает геокодированное местоположение, связанное с введённым адресом. Это свойство содержит сведения о самом местоположении, например, его идентификатор.

Свойство metadata

Это свойство может не заполняться для каждого адреса, обрабатываемого функцией проверки адреса в API JavaScript Карт, но оно указывает, от��ос��т��я ��и ��дрес к типу жилого, делового или почтового ящика.

Свойство uspsData

Это свойство предоставляет полезную информацию о почтовых адресах в США. Однако его полное заполнение не гарантируется для каждого адреса, проверенного сервисом. Поэтому не следует полагаться на это свойство как на единственный способ проверки адресов. Вместо этого проверьте также verdict и address .