Логика проверки сборки

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

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

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

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

Этот документ поможет вам модифицировать вашу систему для оптимального анализа ответа 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, может быть ненадлежащего качества. Рабочий процесс При необходимости проверьте компоненты адреса. Предложите клиенту исправить ошибки в адресе. Запросите подтверждение обновленного адреса. Продолжите, указав адрес. сигналы вердикта Применимо любое из следующих условий: validationGranularity установлен на OTHER . addressComplete имеет значение false .
Подтвердите адрес	В ответе на verdict указан адрес доставки, но в исходные данные внесены изменения: либо исправлены орфографические ошибки, либо данные, которые можно подтвердить. Рабочий процесс Необходимы исправления: При необходимости проверьте компоненты адреса. Запросите подтверждение обновленного адреса. Продолжите, указав адрес. Исправления не требуются: Продолжите, указав адрес. сигналы вердикта Все перечисленные ниже утверждения верны: validationGranularity содержит ROUTE addressComplete имеет true . Если значение поля hasInferredComponents равно true ИЛИ значение поля hasReplacedComponents равно true .
Принять адрес».	Ответ API проверки адреса указывает на отличное качество адреса. Рабочий процесс Продолжите, указав обратный адрес. сигналы вердикта Все перечисленные ниже утверждения верны: validationGranularity содержит PREMISE или более высокий уровень детализации. addressComplete имеет true . Компоненты не были ни предполагаемыми, ни замененными.

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

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

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

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

Уточните адрес

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

Исправить сигналы

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

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

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

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

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

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

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

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 см. в разделе «Обработка адресов в США» .
Адрес для ответа	Содержит поле missingComponentTypes со значением subpremise . Примечание : если поле содержит типы, отличные от subpremise , действие будет отнесено к категории «фиксация адреса». Полный список типов адресов см. в документации по геокодированию.

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

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

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

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

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

1. Детализация валидации

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

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

Оценка качества адреса должна также включать следующие факторы:

• Данные не заменены . В этом случае hasReplacedComponents: FALSE .
• Компоненты не определены . В этом случае hasInferredComponents: FALSE .

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

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

dpvConfirmation	Y Подробную информацию о dpvConfirmation см. в разделе «Обработка адресов в США» .

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