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

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
}

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

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

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

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

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

Если в адресе отсутствуют, неразрешенные или неожиданные компоненты, в поле устанавливается значение 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 .