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

Примечание. В этом документе описаны основные элементы ответа 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 адреса хорошего качества, которое возвращает следующие поля для этого конкретного запроса:

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

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

Подробную информацию можно найти в разделе 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.

Примечание. Если при проверке вручную свойство addressComplete не появляется в заключении, его значение – false. В этом случае вам нужно либо запросить оценку на наличие свойства addressComplete, либо запросить свойство напрямую. Пример приведен в разделе Качество адресов ниже.

См. addressComplete в разделах Verdict и Address справочного руководства.

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

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

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

Подробную информацию можно найти в разделе Verdict справочного руководства.

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

Ниже описана предварительная версия продукта или функции. Поддержка таких продуктов и функций может быть ограничена, а изменения в них – несовместимы с другими предварительными версиями. Использование предварительных версий регулируется Специальными условиями платформы Google Карт. Подробнее об этапах запуска…

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

Свойства address и addressComponent

Важно! Чтобы получить форматирование адреса, используйте свойство address. Используйте его дочерний компонент addressComponent, чтобы изучать ошибки и предоставлять информацию о них клиентам. Однако не следует создавать интеграцию, которая зависит от определенного уровня подтверждения для компонентов адреса. Инструкции по интеграции приведены в разделе Создание логики проверки.

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

Подробнее о Address…

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

Подробнее о addressComponent…

Свойство geocode

Важно! Используйте свойство geocode, чтобы получить геокод или идентификатор места, если ранее в вашей логике вызывался Geocoding API.

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

Подробнее о Geocode…

Свойство metadata

Важно! Используйте свойство metadata, чтобы определить тип объекта, связанного с адресом: жилой дом, абонентский ящик или компания.

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

Ознакомьтесь с информацией о покрытии Address Validation API и справочными материалами по Address metadata.

Свойство uspsData

Важно! Используйте свойство uspsData, чтобы получать уровни достоверности доставки и другие сведения от Почтовой службы США об адресах в США.

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

Ознакомьтесь с разделом Обработка адресов в США и справочной информацией о USPSData.