Создание возможности проверки местоположения с помощью платформы Google Maps

Цель

Часто возникает необходимость проверить местоположение объекта. В платформе Google Maps есть несколько различных сервисов, которые могут помочь в этом. Этот документ поможет вам выбрать один из двух основных сервисов проверки местоположения — API проверки адресов и API геокодирования.

API проверки адресов — это сервис от платформы Google Maps, который помогает пользователям проверять правильность адреса.

Геокодирование с помощью API геокодирования — это процесс преобразования адресов в географические координаты, которые можно использовать для размещения маркеров на карте или указания местоположения на карте.

Общий обзор различий между API проверки адресов и API геокодирования можно найти здесь .

Попробуйте прямо сейчас: перейдите в консоль Google Cloud и включите API проверки адресов и API мест .

Когда выбирать между проверкой адресов и API геокодирования?

Примечания к приведенной выше блок-схеме:

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

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

Вы можете предпочесть использовать API проверки адресов вместо API геокодирования в следующих случаях:

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

Вы можете предпочесть использование геокодирования вместо API проверки адресов в следующих случаях:

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

Ниже приведены несколько примеров, демонстрирующих возможности API проверки адресов в сравнении с API геокодирования.

Пример неверного адреса

Фейк-стрит, 1, Маунтин-Вью, Калифорния 94043, США

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

В городе Маунтин-Вью, штат Калифорния, не существует поддельной улицы (Fake St), и API проверки адресов отражает это в возвращаемых данных на уровне компонентов:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

В данном случае важным свойством, которое следует проверить, является confirmationLevel . Возвращая UNCONFIRMED_BUT_PLAUSIBLE для Fake St, API определяет, что улица может иметь такое название, но не может быть сопоставлена ​​с подтверждающими данными адреса.

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

Используя тот же адрес в API геокодирования, можно найти совпадение с «Калифорнией», как показано на скриншоте из инструмента геокодирования, который вы можете попробовать здесь :

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

Пример орфографической ошибки

76 Buckingamm Palace Road, Лондон , SW1W 9TQ, Великобритания

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

API проверки адресов и API геокодирования способны исправить эти ошибки и получить результат, например, адрес: 76 Buckingham Palace Road, London, SW1W 9TQ. Однако API проверки адресов может предоставить больше информации о процессе.

Взгляните на один из компонентов адреса, который был неправильно написан при вводе:

{
  "componentName": {
    "text": "Buckingham Palace Road",
    "languageCode": "en"
        },
        "componentType": "route",
        "confirmationLevel": "CONFIRMED",
        "spellCorrected": true
     }
}

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

Пример отсутствующих данных и орфографической ошибки

Боллшештрассе 86, 12587, Германия

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

API проверки адресов способен исправить обе эти ошибки и возвращает геокод уровня PREMISE , а также адрес, проверенный на уровне PREMISE :

Bölschestraße 86, 12587 Berlin, DE

В данном случае API геокодирования не может успешно преодолеть ошибки ввода и возвращает результат ZERO_RESULTS .

Пример дополнительных метаданных адреса

111 8th Avenue Ste 123 , Нью-Йорк, штат Нью-Йорк 10011-5201, США

Этот адрес верен, за исключением номера помещения (номер 123), которого в здании нет.

API проверки адреса позволяет проверить адрес PREMISE (111 8th Ave) и предоставить некоторую метаинформацию об объекте, включая информацию о том, что это коммерческое помещение.

помещение:

"business": true

Кроме того, значение dpvConfirmation , возвращаемое в составе uspsData в ответе, имеет вид S :

"dpvConfirmation": "S"

Значение dpvConfirmation равное S указывает на то, что адрес проверен на уровне PREMISE , но номер устройства, указанный во входных данных, не связан с этим адресом.

API геокодирования не может предоставить эту информацию.

Понимание ответа API геокодирования

Обзор

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

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

Например, в случае адреса 123 Example Street, Chicago, 60007, USA решения принимаются в следующем порядке:

Поиск по / Example Street/ Chicago/ 60007/ USA будет производиться в указанном порядке. В данном случае первое совпадение — это Чикаго, а точнее, почтовый индекс 60007 Следовательно, для этого почтового индекса возвращается следующий Place_id:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

API геокодирования содержит в ответе следующую информацию:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

API геокодирования позволяет определить, к какому типу объектов относится данный адрес. Список types адресов, возвращаемых API геокодирования, можно найти здесь .

Если ни один из компонентов входных данных не определен, API возвращает:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

Запрос, содержащий только адрес улицы без номера дома, возвращает результат в следующем формате:

"types": [
  "route"
]

Это означает, что API геокодирования не смог найти или сопоставить номер дома.

Примечание: Чтобы узнать, существует ли адрес, проверьте, заданы ли какие-либо параметры (например, types , partial_match, results, status) в ответе API геокодирования . Это постепенно повысит уровень уверенности в существовании адреса, но не обеспечит 100% точность. Именно поэтому нам нужен API проверки адресов.

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

Тип местоположения

Для правильного понимания этого раздела необходимо разобраться в различных типах местоположения, которые могут быть возвращены в ответе API геокодирования:

• ROOFTOP указывает, что возвращаемый результат представляет собой точный геокод, для которого у нас есть информация о местоположении с точностью до адреса улицы.
• Параметр RANGE_INTERPOLATED указывает, что возвращаемый результат представляет собой приближение (обычно на дороге), интерполированное между двумя точными точками (например, перекрестками). Интерполированные результаты обычно возвращаются, когда геокоды крыш для адреса улицы недоступны.
• Параметр GEOMETRIC_CENTER указывает, что возвращаемый результат представляет собой геометрический центр объекта, такого как полилиния (например, улица) или многоугольник (регион).
• Параметр APPROXIMATE указывает, что возвращаемый результат не соответствует ни одному из вышеперечисленных вариантов.

Если API геокодирования возвращает location_type со значением ROOFTOP или RANGE_INTERPOLATED , это не обязательно означает, что адрес существует. Аналогично, если API геокодирования возвращает значение с флагом partial_match , установленным в true , это все равно может быть правильным результатом для вас.

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

Примечание : Если вы решите использовать API геокодирования, рекомендуется регулярно проводить проверку качества данных между первоначальным запросом и ответом API геокодирования.

Частичное совпадение и ложное совпадение

Если адрес совпадает частично, то есть API геокодирования не смог точно идентифицировать адрес, то ответ будет содержать:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

Ещё важнее, чем указанные выше типы местоположений, является учет момента, когда partial_match = true . В ответе partial_match указывает на то, что API геокодирования не вернул точное совпадение с исходным запросом, хотя и смог сопоставить часть запрошенного адреса.

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

Например, запрос " 21 Henr St, Bristol, UK " возвращает частичное совпадение как для улицы Генри, так и для улицы Генриетты. Обратите внимание, что если запрос содержит орфографическую ошибку в адресе, API геокодирования может предложить альтернативный адрес. Предложения, срабатывающие таким образом, не будут помечены как частичное совпадение.

Синтетические адреса

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

В подобных сценариях объект ответа часто содержит длинный идентификатор места (Place ID) и следующее свойство: geometry.location_type=APPROXIMATE .

Если вы обнаружите эти признаки в ответе, пожалуйста, пометьте введенный адрес как недействительный и попробуйте повторно проверить его другим способом.

Примечание : Это еще один пример использования API проверки адресов, где вы получаете прямую обратную связь, если адрес не существует.

Понимание ответа API проверки адреса

Уже существует отличная документация о том, как понимать ответы от API проверки адресов, поэтому мы не будем вдаваться в дальнейшие подробности.

• Обзор объекта ответа можно найти здесь .
• Демонстрация, показывающая различные компоненты ответа, находится здесь.
• В документе «Проверка адресов при оформлении заказа» подробно описано, как различать корректные и некорректные адреса.

Передовые методы

Указание географического положения

При обращении к API проверки адресов или геокодирования рекомендуется ограничивать географический регион поиска адреса. Оба API реализуют это двумя разными способами:

• API геокодирования — региональная привязка

  Если вы знаете, что геокоды будут находиться в пределах определенной страны, вы получите гораздо лучшие результаты, используя региональную привязку . Например, если вы выполняете геокодирование в Канаде, мы рекомендуем добавить &region=ca к вашим запросам, чтобы сместить акцент в сторону Канады. Обратите внимание, что региональная привязка отдает предпочтение только результатам в пределах этого региона. Вы все еще можете получить результаты за пределами региона.

• API проверки адресов - код региона

  Аналогичным образом, API проверки адресов выдает более точные результаты, если в запросе передается код ISO2 , используя поле regionCode .

Идентификаторы мест хранения

Чтобы сохранить информацию о местоположении из платформы Google Maps для будущих запросов, вы можете хранить идентификатор места (place ID) в базе данных неограниченное время в качестве атрибута местоположения. Вам потребуется отправлять запрос на поиск места только один раз для каждого placeID. Вы также можете искать по placeID каждый раз, когда пользователь запрашивает сведения о транзакции.

Чтобы всегда иметь самую актуальную информацию, обновляйте идентификаторы мест каждые 12 месяцев, используя запрос с подробными сведениями о месте и параметром place_id .

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

Заключение

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

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

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

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

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

• Проверка адреса для оформления заказа в интернет-магазине
• Разместить документ с автозаполнением
• Документация по API проверки адресов
• Отчеты платформы Google Maps

Авторы

Данная статья поддерживается компанией Google. Ее первоначальный автор — следующие лица.

Основные авторы:

Хенрик Вальв | Инженер по решениям

Томас Англаре | Инженер по решениям

Сартак Гангули | Инженер по решениям