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

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

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 суммирует результаты проверки адреса и должно быть первым свойством, которое следует оценивать при построении логики проверки адреса. Это свойство может возвращать различные поля в зависимости от качества выходного адреса. Например, ниже показано свойство 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 .

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

См. addressComplete в разделах «Вердикт» и «Адрес» справочного руководства.

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

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

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

См. Вердикт в справочнике.

Свойства address и addressComponent

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

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

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

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

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

Свойство geocode

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

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

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

Свойство metadata

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

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

См. раздел API проверки адресов и справочную информацию по Address metadata .

Свойство uspsData

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

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

См. Обработка адресов в США и ссылку на UspsData .