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

Цель

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В случае использования функции «Массовая проверка адресов» кэширование данных должно соответствовать Специфическим условиям API проверки адресов, описанным в разделе 11.3. На основании этой информации вы сможете определить, является ли адрес пользователя недействительным, и в этом случае запросите у пользователя исправленный адрес при следующем взаимодействии с вашим приложением.

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

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

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

С согласия пользователя вы можете кэшировать formattedAddress и другие ключевые компоненты ответа. Однако в сценарии без интерфейса (headless) пользователь не может дать согласие, поскольку проверка адреса выполняется бэкендом. Таким образом, в этом сценарии без интерфейса (headless) можно кэшировать лишь ограниченный объём информации.

Понять ответ

Если ответ 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 Карт ограничивают то, какие данные можно кэшировать.

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

Шаг 1:

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

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

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

• confirmationLevel
• inferred
• spellCorrected
• replaced
• unexpected

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

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

Шаг 2:

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

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

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

Заключение

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

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

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

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

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

• Применение проверки адресов большого объема
• Библиотека Python на GitHub
• Ознакомьтесь с демо-версией проверки адреса

Авторы

Эта статья поддерживается Google. Её авторами являются следующие авторы:
Основные авторы:

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