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

Цель

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

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

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

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

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

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

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

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

Регулярная проверка адресов

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

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

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

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

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

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

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

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

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

Реализация безголовой проверки адреса

Судя по обсуждению выше:

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

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

Шаг 1:

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

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

alt_text

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

  • confirmationLevel
  • inferred
  • spellCorrected
  • replaced
  • unexpected

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

Для получения дополнительной информации см. подробную информацию о фактической структуре данных .

Шаг 2:

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

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

alt_text

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

Заключение

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

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

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

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

Рекомендуемое дальнейшее чтение:

Авторы

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

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