Используйте API проверки адресов для обработки адресов в больших объемах.

Цель

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

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

Варианты использования

Теперь мы разберемся, в каких случаях полезна проверка адресов большого объема .

Тестирование

Часто вы хотите протестировать API проверки адресов, запустив тысячи адресов. У вас могут быть адреса в файле Comma Separated Value, и вы хотите проверить качество адресов.

Однократная проверка адресов

При подключении к API проверки адресов вам необходимо проверить существующую базу данных адресов по базе данных пользователей.

Повторная проверка адресов

Ряд сценариев требуют периодической проверки адресов:

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

Техническое глубокое погружение

Для целей настоящего документа мы предполагаем, что:

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

Кэш для производственного использования

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

Для варианта использования High Volume Address Validation кэширование данных должно соответствовать Специфическим условиям API Address Validation Service , изложенным в Разделе 11.3. На основе этой информации вы сможете определить, может ли адрес пользователя быть недействительным, и в этом случае вы запросите у пользователя исправленный адрес во время его следующего взаимодействия с вашим приложением.

  • Данные из объекта AddressComponent
    • confirmationLevel
    • inferred
    • spellCorrected
    • replaced
    • unexpected

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

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

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

Понять ответ

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

  • Маркер addressComplete в объекте Verdict имеет true ,
  • validationGranularity в объекте Verdict — PREMISE или SUB_PREMISE
  • Ни один из AddressComponent не помечен как:
    • Inferred (Примечание : inferred=true может иметь место, когда addressComplete=true )
    • spellCorrected
    • replaced
    • unexpected и
  • confirmationLevel : уровень подтверждения для AddressComponent установлен на CONFIRMED или UNCONFIRMED_BUT_PLAUSIBLE

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

  • formattedAddress
  • postalAddress
  • addressComponent componentNames или
  • UspsData standardizedAddress

Реализовать проверку адреса без заголовка

На основании вышеизложенного:

  • Часто бывает необходимо кэшировать некоторую часть ответа от API проверки адресов по деловым причинам.
  • Однако Условия обслуживания платформы Google Карт ограничивают объем данных, которые могут кэшироваться.

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

Шаг 1:

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

Диаграмма A: На следующей диаграмме показано, как можно улучшить конвейер данных с помощью логики проверки адресов большого объема.

alt_text

Согласно Условиям обслуживания, вы можете кэшировать следующие данные из addressComponent :

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

Таким образом, на этом этапе реализации мы будем кэшировать вышеупомянутые поля по отношению к UserID.

Более подробную информацию см. в разделе «Подробности фактической структуры данных» .

Шаг 2:

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

Диаграмма B : На этой диаграмме показано, как может выглядеть сквозная интеграция процесса получения согласия пользователя:

alt_text

  1. Когда пользователь входит в систему, сначала проверьте, кэшированы ли в вашей системе какие-либо флаги проверки.
  2. Если есть флаги, вы должны предоставить пользователю пользовательский интерфейс для исправления и обновления его адреса.
  3. Вы можете снова вызвать API проверки адреса с обновленным или кэшированным адресом и предоставить исправленный адрес пользователю для подтверждения.
  4. Если адрес хорошего качества, API проверки адреса возвращает formattedAddress .
  5. Вы можете либо предоставить этот адрес пользователю, если были внесены исправления, либо молча принять его, если исправлений нет.
  6. После того, как пользователь примет приглашение, вы можете кэшировать formattedAddress в базе данных.

Заключение

High Volume Address Validation — это распространенный вариант использования, с которым вы, вероятно, столкнетесь во многих приложениях. В этом документе предпринята попытка продемонстрировать некоторые сценарии и шаблон проектирования для реализации такого решения в соответствии с Условиями обслуживания платформы Google Карт.

Мы также написали эталонную реализацию High Volume Address Validation в виде библиотеки с открытым исходным кодом на GitHub. Ознакомьтесь с ней, чтобы быстро начать разработку с High Volume Address Validation. Также посетите статью о шаблонах проектирования, как использовать библиотеку в различных сценариях.

Следующие шаги

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

Рекомендуемая дополнительная литература:

Участники

Google поддерживает эту статью. Ее первоначально написали следующие участники.
Основные авторы:

Хенрик Валв | Инженер по решениям
Томас Англерет | Инженер по решениям
Сартак Гангули | Инженер по решениям