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

Примечание: В этом документе описаны основные элементы ответа проверки адреса высокого качества. Рекомендации по работе с реальными сценариями адресов и построению логики для более сложных ответов см. в разделе «Построение логики проверки» .

Ответ 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 — описывает уровень детализации адреса, отправляемого в JavaScript API проверки адресов в Maps. Уровень детализации адреса в запросе влияет на уровень детализации адреса в ответе проверки. Например, адрес с inputGranularity ниже уровня PREMISE обычно не приводит к уровню validationGranularity PREMISE .
• validationGranularity — Уровень детализации, до которого API проверки адресов в картах JavaScript может полностью проверить адрес. В большинстве случаев уровень детализации 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
}

См. заключение в справочном руководстве.

Возможный следующий шаг

Этот продукт или функция находятся в режиме предварительного просмотра (pre-GA). Продукты и функции pre-GA могут иметь ограниченную поддержку, а изменения в продуктах и ​​функциях pre-GA могут быть несовместимы с другими версиями pre-GA. На предложения pre-GA распространяются специальные условия использования сервиса Google Maps Platform . Для получения дополнительной информации см. описания этапов запуска .

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

Свойства address и addressComponent

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

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

См. Address в справочном руководстве.

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

См. addressComponent в справочном руководстве.

Свойство geocode

Ключевой момент: используйте свойство geocode для удобства получения геокода или идентификатора места, когда ваша логика ранее вызывала API геокодирования.

Свойство geocode указывает геолокацию, связанную с введенным адресом. Это свойство предоставляет подробную информацию о самом местоположении, например, его идентификатор места (place ID).

См. раздел Geocode в справочном руководстве.

Свойство metadata

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

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

См. описание API проверки адресов и справочник по Address metadata .

Свойство uspsData

Ключевой момент: используйте свойство uspsData для получения информации об уровнях достоверности доставки и других данных USPS об адресах в США.

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

См. раздел «Обработка адресов в США» и справочник USPSData .