Используйте 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

  • Согласно Условиям обслуживания, вы можете кэшировать addressComplete, validationGranularity and validationFlags при проверке адресов в автономном режиме.

  • Вы можете кэшировать addressComplete,validationGranularity and validationFlags, PlaceID относительно определенного UserID в базе данных клиентов.

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

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

Шаг 2:

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

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

alt_text

  1. Когда пользователь входит в систему, сначала проверьте, не кэшировали ли вы в своей системе какие-либо флаги проверки, например:

    • addressComplete имеет значение true
    • validationGranularity не является PREMISE или SUB_PREMISE
    • validationFlags inferred,spellCorrected,replaced,unexpected .
      • Если флагов нет, существует высокая уверенность в том, что существующий кэшированный адрес хорошего качества и его можно использовать.

  2. Если есть флаги, вы должны предоставить пользователю пользовательский интерфейс для исправления/обновления своего адреса.

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

  4. Если адрес хорошего качества, API проверки адреса возвращает formattedAddress .

  5. Вы можете либо предоставить этот адрес пользователю, если были внесены исправления, либо молча принять, если исправлений нет.

  6. Как только пользователь согласится, вы сможете кэшировать formattedAddress в базе данных.

Псевдокод, реализующий шаг 2:

If addressComplete is FALSE

OR

If validationGranularity is Not PREMISE OR SUB_PREMISE

OR

If validationFlags is inferred OR spellCorrected OR replaced OR unexpected
  {

    # This means there are issues with the existing cached address

    Call UI to present the address to user

}
Else{

    # This means existing address is good
  Proceed to checkout
}

Заключение

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

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

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

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

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

Авторы

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

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