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

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

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

• Исправление — адрес некачественный. Вам следует запросить дополнительную информацию.
• Confirm — адрес высокого качества, но имеет изменения по сравнению с входным адресом. Вы можете запросить подтверждение.
• 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 и не являются единственными сигналами, которые необходимо проверять, они предоставляют начальный индикатор качества адреса. Каждому типу поведения соответствует раздел в этом документе, описывающий дополнительные сигналы, которые вам также может потребоваться изучить.

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

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

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

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

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

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

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

Примечание. Когда вы повторяете запросы к API проверки адреса для одного и того же адреса, вы можете вызвать метод provideValidationFeedback , чтобы указать результат. См . раздел «Обработка адресов в США» .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание. Учитывайте свой уровень риска , решая, следует ли подтвердить адрес клиенту или признать его действительным. Кроме того, если вы повторно отправляете запросы к API проверки адреса, вы можете выполнить вызов provideValidationFeedback чтобы сообщить о своем результате. См. раздел «Обработка обновленных адресов» .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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