Создайте свою логику проверки

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

В общем случае ответ API определяет следующие способы обработки адреса вашей системой:

• handyman Исправление — адрес некачественный. Вам следует запросить дополнительную информацию.
• edit Confirm — адрес высокого качества, но имеет изменения по сравнению с входным адресом. Вы можете запросить подтверждение.
• check Accept — адрес высокого качества. Вы можете принять предоставленный адрес.

Основная цель

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

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

Обзор рабочего процесса

В таблице ниже приведены два действия для вашей системы:

1. Используемый рабочий процесс основан на поведении «исправить, подтвердить, принять».
2. Первые сигналы, которые следует проверить из ответа. Описанные здесь сигналы исходят из свойства verdict и не являются единственными сигналами, которые необходимо проверять, они предоставляют начальный индикатор качества адреса. Каждому типу поведения соответствует раздел в этом документе, описывающий дополнительные сигналы, которые вам также может потребоваться изучить.

Поведение вашей системы
handyman Исправить адрес	В ответе на verdict указывается важная недостающая информация, которую следует предоставить. Адрес, возвращаемый API проверки адреса, может быть неудовлетворительного качества. Рабочий процесс При необходимости изучите компоненты адреса. Попросите клиента устранить проблемы с адресом. Запросить проверку обновленного адреса. (Необязательно) Отправьте запрос в конечную точку обратной связи для API. См. раздел «Обработка обновленных адресов» . Продолжайте с адресом. Сигналы вердикта Применимо любое из следующих условий: validationGranularity установлен на OTHER . См. значения детализации . addressComplete имеет значение false .
edit Подтвердить адрес	Ответ на verdict указывает адрес доставки, но в исходный ввод внесены изменения: выводятся данные, которые либо исправлены по орфографии, либо данные, которые могут быть подтверждены. Рабочий процесс Необходимые исправления: При необходимости изучите компоненты адреса. Запросить проверку обновленного адреса. (Необязательно) Отправьте запрос в конечную точку обратной связи для API. См. раздел «Обработка обновленных адресов» . Продолжайте с адресом. Никаких исправлений не требуется: (Необязательно) Отправьте запрос в конечную точку обратной связи для API. См. раздел «Обработка обновленных адресов» . Продолжайте с адресом. Сигналы вердикта Применяется все следующее: validationGranularity содержит ROUTE или лучше. См. значения детализации . addressComplete имеет значение true . Поле hasInferredComponents имеет true ИЛИ поле hasReplacedComponents имеет true .
check Принять адрес	Ответ API проверки адреса указывает на адрес превосходного качества. Рабочий процесс Продолжите с возвращенным адресом. Сигналы вердикта Применяется все следующее: validationGranularity содержит PREMISE или лучше. См. значения детализации . addressComplete имеет значение true . Никаких предполагаемых или замененных компонентов.

Руководство по внедрению

При проектировании реакции вашей системы на сигналы API проверки адреса следующие рекомендации помогут вам построить более эффективную модель ответа. Однако это всего лишь рекомендации, поэтому имейте в виду, что ваша реализация должна соответствовать вашей бизнес-модели.

	Руководство	Подробности
Уровень риска	Примите во внимание уровень толерантности к вашей ситуации, балансируя между запросом на исправления и принятием введенного адреса.	API проверки адреса возвращает различные сигналы, которые вы можете включить в свой уровень риска, чтобы оптимизировать процесс проверки. Например, если адрес имеет неподтвержденный номер улицы, вы все равно можете его принять. С другой стороны, если ваша бизнес-операция требует большей точности адреса, вы можете предложить этому пользователю. Пример, который может относиться к любой из категорий, см. в разделе «Неподтвержденный номер улицы за пределами США» в разделе «Принять адрес — примеры» .
Принимать адреса	Хорошей практикой является разрешение вашей системе принимать исходную запись, если клиент не отвечает на запросы.	В этих случаях клиент мог ввести адрес, которого нет в системе, например, для нового строительства.
Обеспечить обратную связь	При повторной отправке запроса на проверку адреса вы также можете отправить запрос в конечную точку provideValidationFeedback .	Это позволит Google узнать, как вы в конечном итоге обработали окончательный ответ. См. раздел «Обработка обновленных адресов» .

Исправить адрес

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

Фиксировать сигналы

API проверки адреса предоставляет ряд сигналов, позволяющих узнать, следует ли исправить адрес.

1. Детализация валидации и недостающие компоненты

Эти два сигнала лучше всего указывают на проблемный адрес:

• Если поле validationGranularity имеет значение OTHER , ваша система должна изучить сигналы компонентов адреса, чтобы узнать больше о том, где произошла ошибка и как ее исправить.
• Всякий раз, когда объект address после постобработки возвращает missingComponentTypes поле ComponentTypes, ваша система должна проверить наличие этого компонента. Отсутствие компонентов также делает адрес неполным и невозможным для доставки.

2. Другие сигналы

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

Подозрительные компоненты	Если перечисление уровня подтверждения для компонента — UNCOMFIRMED_AND_SUSPICIOUS , вполне вероятно, что компонент неверен.
Неразрешенный компонент	Неразрешенный токен — это часть ввода, которая не распознается как допустимая часть адреса.

3. Сигналы адреса США

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

dpvConfirmation	Либо N , D , либо пусто.

Дополнительные сведения о dpvConfirmation см. в разделе Обработка адресов в США .

Примеры исправленных адресов

Подтвердить адрес

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

Чтобы предоставить клиенту правильные подсказки, ваша логика будет идентифицировать компоненты, помеченные службой, чтобы определить, какое действие или флаг API применил к компоненту, например inferred , replaced или spellCorrected . См. AddressComponent в справочнике.

Подтвердить сигналы

API проверки адреса предоставляет ряд сигналов, позволяющих узнать, следует ли подтвердить адрес.

1. Детализация проверки

validationGranularity ROUTE или выше приемлема, но PREMISE или SUBPREMISE обеспечивают более сильный сигнал о доставляемости.

2. Другие сигналы

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

Предполагаемые данные	Если поле hasInferredComponents имеет значение true , вы знаете, что API заполнил информацию, полученную из других компонентов адреса.
Замененные данные	Если поле hasReplacedComponents имеет значение true , API заменяет введенные данные данными, которые, по его мнению, делают адрес действительным.

3. Сигналы адреса США

Некоторые поля, применимые только к адресам в США, указывают, что ваша логика должна подтвердить детали с клиентом. Применяется одно из следующих условий:

dpvConfirmation	S Дополнительные сведения о dpvConfirmation см. в разделе Обработка адресов в США .
Адресный ответ	Содержит поле missingComponentType со значением subpremise .

Примеры подтверждения адреса

Принять адрес

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

Принимать сигналы

API проверки адреса предоставляет ряд сигналов, позволяющих узнать, следует ли подтвердить адрес.

1. Детализация проверки

validationGranularity PREMISE или выше приемлема, но в некоторых случаях ROUTE по-прежнему указывает адрес доставки.

2. Другие сигналы

В вердикте о качестве адреса также должно быть указано следующее:

• Никаких замененных данных . В данном случае hasReplacedComponents: FALSE .
• Никаких предполагаемых компонентов . В данном случае hasInferredComponents: FALSE .

3. Сигналы адреса США

Некоторые поля, применимые только к адресам в США, указывают адрес высокого качества, на который можно доставить. Для приемлемого адреса в США вы должны увидеть следующее:

dpvConfirmation	Y Дополнительные сведения о dpvConfirmation см. в разделе Обработка адресов в США .

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