Краткий справочник по Address Validation API

Address Validation API принимает адрес, определяет и проверяет его компоненты, стандартизирует адрес для почтовой рассылки и возвращает наиболее точные координаты широты и долготы для него. Для адресов в США и Пуэрто-Рико можно включить обработку USPS CASS.

Address Validation API: основные факты

  • Продукт: Address Validation API.
  • Категория: Места
  • Платформа: веб-сервис (REST).
  • Где выполняется: на сервере (код бэкенда).
  • Стадия запуска: GA
  • Жизненный цикл: активно.
  • Общие сведения: Общие сведения об Address Validation API
  • Регионы: ограниченное количество. Поддерживаемые страны и качество данных зависят от страны. Некоторые страны находятся на этапе предварительной версии. Метаданные о жилых и коммерческих зданиях возвращаются только для стран, отмеченных на странице покрытия. USPS CASS поддерживается только в США и Пуэрто-Рико. (подробнее о покрытии)

Когда использовать Address Validation API

Используйте Address Validation API, если:

  • Вам нужно проверить, существует ли адрес, и найти, какие компоненты отсутствуют или могут быть неверными.
  • Вам нужно стандартизировать и дополнить почтовый адрес, например при оформлении заказа.
  • Для адресов в США и Пуэрто-Рико требуется проверка USPS CASS и uspsData.
  • Вам нужны метаданные адресов жилых или коммерческих зданий для страны, указанной на странице покрытия.

Когда не следует использовать Address Validation API

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

Настройка Address Validation API

Официальные пакеты Address Validation API:

  • npm: @googlemaps/addressvalidation
  • pypi: google-maps-addressvalidation
  • go: cloud.google.com/go/maps

Address Validation API: распространенные ошибки

  • Проблема. Свойство addressComplete не включается в результат, если его значение – false. Поэтому код, который ожидает наличия этого поля, может неправильно интерпретировать неполные адреса. Решение. Считайте, что отсутствующее свойство addressComplete имеет значение false, или проверяйте наличие свойства. Подробнее: /maps/documentation/address-validation/understand-response.
  • Проблема. Если параметр regionCode не указан, API определяет регион по адресу, что может привести к менее точным результатам. Решение. Если вам известен идентификатор regionCode, добавьте его в параметр PostalAddress. Подробнее: /maps/documentation/address-validation/requests-validate-address.
  • Проблема. Нет гарантии, что объект uspsData будет полностью заполнен для каждого подтвержденного адреса в США. Решение. Не полагайтесь на uspsData как на единственный сигнал проверки. Также используйте вердикт и компоненты адреса. Подробнее: /maps/documentation/address-validation/handle-us-address.
  • Проблема. Отзыв, отправленный с помощью provideValidationFeedback, должен ссылаться на responseId из первого вызова validateAddress в последовательности, а не из последующего. Решение. Сохраните responseId из первого ответа validateAddress и отправьте его в запросе обратной связи. Подробнее о том, /maps/documentation/address-validation/handle-updated-address…

Что можно делать с помощью Address Validation API

Ниже приведены ссылки на руководства по каждой задаче. Вы также можете сравнить возможности продуктов в Обзоре возможностей.