В этом документе описывается процесс создания системы проверки адресов, которая может обрабатывать различные ответы от Address Validation API. Вы узнаете, как правильно использовать ответ, изучать другие сигналы от API, а также когда и как запрашивать у клиентов дополнительную информацию.
В целом ответ API определяет следующие способы обработки адреса вашей системой:
- Исправить – адрес низкого качества. Вам следует запросить дополнительную информацию.
- Confirm (Подтвердить) – адрес высокого качества, но отличается от введенного. Вы можете запросить подтверждение.
- Принять – адрес высокого качества. Вы можете принять предложенный адрес.
Основная цель
Этот документ поможет вам изменить систему, чтобы лучше анализировать ответы API и определять, какие действия следует предпринять с предоставленными адресами. Ниже приведен пример псевдокода.
if (the API response indicates significant problems in the address)
FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
CONFIRM - confirm with the user that the address is correct
else
ACCEPT - continue with the address returned by the API.
Точная логика зависит от вашей ситуации. Подробную информацию вы найдете в руководстве по реализации. Вы также можете использовать нашу реализацию этой логики с открытым исходным кодом, которая находится в расширенной библиотеке компонентов.
Обзор рабочего процесса
В таблице ниже приведены два действия для вашей системы.
- Рабочий процесс, основанный на исправлении, подтверждении и принятии.
- Первые сигналы, которые нужно проверить в ответе. Описанные здесь сигналы поступают из свойства
verdict. Это не единственные сигналы, которые нужно проверять, но они дают первоначальное представление о качестве адреса. Каждому типу поведения соответствует раздел в этом документе, в котором описываются дополнительные сигналы, которые вам также может потребоваться исследовать.
| Поведение системы | |||
|---|---|---|---|
| Исправить адрес |
Ответ от
|
||
| Подтвердить адрес |
Ответ от
|
||
| Принять адрес |
Ответ Address Validation API указывает на отличное качество адреса.
|
||
Советы по размещению рекламы
При разработке системы реагирования на сигналы Address Validation следующие рекомендации помогут вам создать более эффективную модель реагирования. Однако это лишь рекомендации, и вы можете выбрать другой вариант, который лучше подходит для вашей бизнес-модели.
| Рекомендации | Подробнее… | |
|---|---|---|
| Уровень риска |
Принимая решение о том, запрашивать ли исправления или принимать адрес в том виде, в котором он введен, учитывайте уровень допустимости для вашей ситуации. |
Address Validation API возвращает различные сигналы, которые вы можете использовать вместе с уровнем риска, чтобы оптимизировать процесс проверки. Например, если в адресе не подтвержден номер дома, вы все равно можете принять его. Если же для вашей коммерческой деятельности требуется более высокая точность адреса, вы можете запросить у пользователя дополнительные сведения. Пример, который может относиться к любой из категорий, приведен в разделе Неподтвержденный номер дома за пределами США статьи Примеры адресов, которые можно принять. |
| Принять адреса |
Рекомендуется настроить систему так, чтобы она принимала исходный вариант, если клиент не отвечает на подсказки. |
В таких случаях клиент мог ввести адрес, которого нет в системе, например адрес нового здания. |
Исправить адрес
Исправьте адрес, если результаты явно указывают на то, что он недействителен. После этого ваша система может предложить клиенту предоставить необходимую информацию, а затем вы повторно запустите рабочий процесс, чтобы получить адрес доставки.
Исправить сигналы
Address Validation API предоставляет ряд сигналов, которые позволяют узнать, нужно ли исправить адрес.
1. Детализация проверки и отсутствующие компоненты
На проблемы с адресом указывают два сигнала:
- Если поле
validationGranularityимеет значениеOTHER, ваша система должна проанализировать сигналы компонентов адреса, чтобы узнать больше о том, где произошла ошибка и как ее исправить. - Если обработанный объект
addressвозвращает полеmissingComponentTypes, ваша система должна проверить этот компонент. Если в адресе отсутствуют какие-либо компоненты, он считается неполным и доставка по нему невозможна.
2. Другие сигналы
Address Validation API также предоставляет другие сигналы, помогающие диагностировать конкретные проблемы:
| Подозрительные компоненты | Если для компонента задано перечисление уровня подтверждения UNCOMFIRMED_AND_SUSPICIOUS, то, скорее всего, компонент указан неверно.
|
|---|---|
| Неразрешенный компонент | unresolvedToken – часть входных данных, которая не распознана как действительная часть адреса. |
3. Сигналы адресов в США
Некоторые поля, применимые только к адресам в США, предоставляют полезный сигнал о том, что адрес не может быть доставлен и должен быть исправлен. Для адреса, который требует исправления, вы должны увидеть следующее:
dpvConfirmation
|
N, D или пустое значение.
|
|---|
Подробнее о dpvConfirmation читайте в статье Обработка адресов в США.
Как подтвердить адрес
Подтверждение адреса требуется, если в вердикте указано, что Address Validation API вывел или изменил компоненты адреса, чтобы получить подтвержденный адрес. В таких случаях у вас есть адрес, на который можно доставить посылку, но вы хотите быть уверены, что он совпадает с адресом, указанным клиентом.
Чтобы предоставить клиенту правильную подсказку, ваша логика должна идентифицировать компоненты, помеченные сервисом, и определить, какое действие или пометку API применил к компоненту, например inferred, replaced или spellCorrected.
См. AddressComponent в справочнике.
Подтвердить сигналы
Address Validation API предоставляет ряд сигналов, позволяющих узнать, следует ли подтвердить адрес.
1. Детализация проверки
Допустимо значение validationGranularity, равное ROUTE или выше, но PREMISE или SUBPREMISE – более надежный показатель доставляемости.
2. Другие сигналы
Если вы решите подтвердить адрес у клиента, вердикт также предоставит следующие данные, чтобы определить, какие компоненты следует проверить:
| Выведенные данные | Если поле
hasInferredComponents имеет значение true, это означает, что API заполнил информацию, полученную из других компонентов адреса.
|
|---|---|
| Замененные данные | Если поле
hasReplacedComponents имеет значение true, API заменил введенные данные на те, которые посчитал правильными.
|
3. Сигналы адресов в США
Некоторые поля, применимые только к адресам в США, указывают на то, что ваша логика должна подтверждать данные у клиента. Выполняется одно из следующих условий:
dpvConfirmation
|
S
Подробную информацию о |
|---|---|
| Ответ на запрос адреса | Содержит поле missingComponentTypes со значением subpremise.
|
Как принять адрес
Вы принимаете адрес, когда оценка дает высокую степень уверенности в том, что адрес может быть доставлен и может использоваться без дальнейшего взаимодействия с клиентом в последующем процессе.
Принимать сигналы
Address Validation API предоставляет ряд сигналов, позволяющих узнать, нужно ли подтверждать адрес.
1. Детализация проверки
Значение validationGranularity, равное PREMISE или выше, считается приемлемым, но в некоторых случаях значение ROUTE также указывает на то, что адрес существует.
2. Другие сигналы
Для адреса высокого качества также должны быть указаны следующие данные:
- Данные не заменяются. В этом случае
hasReplacedComponents: FALSE. - Нет предполагаемых компонентов. В этом случае
hasInferredComponents: FALSE.
3. Сигналы адресов в США
Некоторые поля, применимые только к адресам в США, указывают на высокое качество адреса, по которому можно доставить посылку. Если адрес в США указан правильно, вы увидите следующее:
dpvConfirmation
|
Y
Подробнее о
|
|---|