Как интерпретировать базовый ответ Address Validation API

Ответ Address Validation 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 – описывает уровень детализации, полученный из адреса, отправленного в Address Validation в Maps JavaScript API. Уровень детализации адреса в запросе влияет на уровень детализации адреса в ответе на проверку. Например, адрес с inputGranularity ниже уровня PREMISE обычно не приводит к validationGranularity до уровня PREMISE.
• validationGranularity – уровень детализации, до которого Address Validation в 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, который предоставляет подробный список элементов (или компонентов) адреса, обработанных Address Validation в Maps JavaScript API. API идентифицирует каждое поле компонента по его названию, типу и уровню подтверждения.

Свойство geocode

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

Свойство metadata

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

Свойство uspsData

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