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

API проверки адресов предоставляет тело ответа в виде объекта JSON, который содержит два свойства верхнего уровня:

• result , объект типа ValidationResult
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // 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"
}

В этом документе основное внимание уделяется объекту result . Для получения информации о responseID см. Обработка обновленных адресов .

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

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

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

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

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

Свойство possibleNextAction предлагает интерпретационное резюме остальной части ответа API с целью помочь вам определить, следует ли вам предлагать клиенту просмотреть или внести изменения в свой адрес. Подробнее см. в разделе Создание логики проверки .

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

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

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

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

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

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

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

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

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

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

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

Свойства address и addressComponent

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

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

Свойство geocode

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

Свойство metadata

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

Свойство uspsData

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