Подтвердить адрес – примеры

В этом документе описывается ряд реальных сценариев, в которых API проверки адресов предоставляет сигналы ответа для адресов, которые могут потребовать подтверждения от вашей системы. См. примеры рабочих процессов в разделе «Создание логики проверки» для получения более подробной информации.

Распространенные примеры: подтвердить

Следующий пример иллюстрирует случай мегаполисов с похожими названиями улиц. Предположим, пользователь хочет ввести адрес здания Google D в Киркленде, штат Вашингтон, США . Однако вместо Киркленда он случайно вводит Сиэтл .

Адрес введен Область
Здание D, 451 7th Avenue South, Сиэтл, Вашингтон 98033 НАС

Вердикт по замененным данным

В примере ниже подчеркиваются важные сигналы ответа.

{
  "inputGranularity": "SUB_PREMISE",
  "validationGranularity": "PREMISE_PROXIMITY",
  "geocodeGranularity": "PREMISE_PROXIMITY",
  "addressComplete": true,
  "hasUnconfirmedComponents": true
  "hasReplacedComponents": true,
  "possibleNextAction": "CONFIRM"
}

Действие possibleNextAction даёт предварительное указание на то, что, возможно, стоит уточнить адрес у клиента. Другие сигналы в вердикте предоставляют более подробную информацию о возможных проблемах с адресом. PREMISE_PROXIMITY указывает на близость к адресу на уровне здания, но не так детализирован, как SUB_PREMISE , который представляет собой уровень детализации, предоставляемый при вводе. Ответ также содержит как неподтверждённые, так и заменённые компоненты.

Проверка компонентов адреса выявляет следующие проблемные области:

{
  "componentName": {
    "text": "451",
  },
  "componentType": "street_number",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
...
{
  "componentName": {
    "text": "98104",
  },
  "componentType": "postal_code",
  "confirmationLevel": "CONFIRMED",
  "replaced": true
}
...
{
  "componentName": {
    "text": "Building D",
    "language_code": "en"
  },
  "componentType": "subpremise",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
}
.......

    "unconfirmedComponentTypes": [
      "street_number",
      "subpremise"
    ]

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

Примеры пограничных случаев: подтверждение

Следующие примеры иллюстрируют следующие типы крайних случаев:

Незначительные выводы, которые ПОДТВЕРЖДЕНЫ

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

  • Город
  • Состояние
  • Почтовый индекс
  • Страна

Например, клиент указывает действительный почтовый адрес ресторана McDonald's в Спрингфилде, штат Массачусетс, но забывает указать город и указывает почтовый индекс без четырехзначного расширения.

Адрес введен Область
1402 Аллен Стрит, Массачусетс 01118 НАС

Вердикт по пропавшему городу 

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "hasInferredComponents": true,
  "possibleNextAction": "CONFIRM"
}

В ситуациях, когда API проверки адресов выводит компоненты более высокого уровня для определения адреса доставки, вы можете быть более уверены в корректности данных системы. Это связано с тем, что выведенные компоненты, представляющие широкий географический регион, легче сопоставляются с подтверждёнными компонентами адреса, которые являются более детализированными. Даже в странах, где названия городов повторяются, например, в Спрингфилде в США, сочетание других компонентов может обеспечить уникальный адрес.

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

{
  "componentName": {
    "text": "Springfield",
    "languageCode": "en"
  },
  "componentType": "locality",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
},
{
  "componentName": {
    "text": "1806"
  },
  "componentType": "postal_code_suffix",
  "confirmationLevel": "CONFIRMED",
  "inferred": true
}

Неожиданный компонент адреса НЕ подтвержден

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

Например, адрес может относиться к региону, где клиенты часто вводят безобидную информацию, игнорируемую почтовыми службами, и в этом случае вы примете адрес. Однако в некоторых случаях неподтверждённый компонент может не соответствовать требованиям клиента.

Адрес введен Область
59 Cherrydown Avenue, Чингфорд, Лондон E4 8DT Великобритания

Вердикт по неожиданному компоненту адреса не подтверждён 

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

Помимо вердикта с неподтвержденными компонентами, API проверки адреса возвращает следующий отформатированный адрес:

"formattedAddress": "59 Cherrydown Avenue, London E4 8DT, UK",

Сканирование на наличие неподтвержденных компонентов показывает, что API удалил Чингфорд из возвращенного адреса:

{
  "componentName": {
    "text": "Chingford",
    "languageCode": "en"
  },
  "componentType": "sublocality_level_1",
  "confirmationLevel": "UNCONFIRMED_BUT_PLAUSIBLE",
  "unexpected": true
}

Неожиданный компонент адреса, который подтвержден

Этот пример иллюстрирует включение графства Великобритании в указанный адрес, что является распространённой практикой. Однако это не является требованием почтовой службы Великобритании и фактически игнорируется. См. postoffice.co.uk и раздел «Как адресовать почтовые отправления в Великобритании и за рубежом» .

В результате, когда клиент указывает графство в своем адресе в Великобритании, служба оценивает это как неожиданные данные.

Адрес введен Область
33 Dunalley St, Челтнем, Глостершир, GL50 4AP Великобритания

Вердикт по неожиданному компоненту адреса, который был подтвержден IS 

{
   "inputGranularity": "PREMISE",
   "validationGranularity": "PREMISE",
   "geocodeGranularity": "PREMISE",
   "possibleNextAction": "ACCEPT"
}

В данном случае address_complete оценивается как false, а анализ компонента address выявляет неожиданный флаг.

{
  "componentName": {
    "text": "Gloucestershire",
    "languageCode": "en"
  },
  "componentType": "administrative_area_level_2",
  "confirmationLevel": "CONFIRMED",
  "unexpected": true
}

Хотя графство Глостершир указано верно для введённого адреса, сам адрес имеет неверный формат. Напомним, что API проверки адресов также проверяет правильность форматирования информации.