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

Geocoding API – это веб-сервис, который преобразует адреса в координаты и идентификаторы мест, а также координаты или идентификаторы мест в адреса. Метод SearchDestinations версии 4 также возвращает сведения о пункте назначения, например о входах в здания, навигационных точках, контурах зданий и территорий, а также о ближайших ориентирах.

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

  • Продукт: Geocoding API.
  • Категория: Места
  • Платформа: веб-сервис (REST).
  • Где выполняется: на сервере (код бэкенда).
  • Стадия запуска: GA
  • Жизненный цикл: активно.
  • Обзор: Обзор Geocoding API

Geocoding API: когда использовать

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

  • Вам нужно преобразовать почтовый адрес в координаты (широту и долготу) и идентификатор места на бэкенд-сервере.
  • Для GPS-координат или известного идентификатора места нужен отображаемый адрес или административный район (город, почтовый индекс).
  • Чтобы направлять водителей или курьеров к пункту назначения, вам нужны входы в здания, навигационные точки маршрута или контуры зданий/территорий.
  • Вам нужно разбить пункт назначения, находящийся внутри большого комплекса (аэропорта, торгового центра, кампуса), на подпункты или близлежащие ориентиры.

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

  • Вам нужно геокодирование из клиентского JavaScript в браузере; вызов версии 4 с открытым ключом API представляет угрозу безопасности. Используйте Maps JavaScript API.
  • Вам нужно рассчитать маршрут или расчетное время прибытия в пункт назначения, для которого выполнено геокодирование. Используйте Routes API.
  • Вам нужны пошаговые инструкции по навигации к токену точки навигации в приложении для Android. Используйте Navigation SDK для Android.
  • Вам нужны пошаговые инструкции по навигации к токену точки навигации в приложении для iOS. Используйте Navigation SDK для iOS.

Geocoding API: настройка

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

  • Проблема. Запросы SearchDestinations без маски поля завершаются ошибкой. В отличие от GeocodeAddress, GeocodeLocation и GeocodePlace, маска поля обязательна. Решение. Установите заголовок X-Goog-FieldMask или параметр $fields для каждого запроса SearchDestinations. Подробнее /maps/documentation/geocoding/choose-fields…
  • Проблема. В v4 GeocodeAddress нет жесткого фильтра компонентов (v3 components=country:US). Структурированные параметры address.* объединяются в один адрес и не фильтруют результаты. В v4 также нет значения по умолчанию для regionCode (в v3 по умолчанию использовалось us). Решение. Фильтруйте results на стороне клиента: сопоставляйте regionCode в верхнем регистре с postalAddress.regionCode; сопоставляйте двухбуквенные коды административных регионов в верхнем регистре с postalAddress.administrativeArea и administrative_area_level_n addressComponents (shortText); нормализуйте входные данные и postalAddress.postalCode (удалите пробелы и дефисы и примените региональные правила). Подробнее: /maps/documentation/geocoding/geocoding-v4-migrate.
  • Проблема. Вызов Geocoding API версии 4 непосредственно из кода JavaScript в браузере раскрывает ключ API. Ограничения по заголовку HTTP referer можно обойти, подделав заголовок Referer. Решение. Вызывайте версию 4 из собственного бэкенда с защищенным ключом или используйте сервис геокодирования Maps JavaScript API (бэкенд версии 3) для клиентских нужд. Подробнее: /maps/documentation/geocoding/geocoding-v4-migrate.
  • Проблема. В отличие от версии 3 и других методов версии 4, SearchDestinations может возвращать результаты, в которых нет точного основного адреса. Решение. Если вам нужны только результаты с точными основными адресами, задайте для параметра placeFilter.addressability значение PRIMARY. Подробнее: /maps/documentation/geocoding/geocoding-v4-migrate.
  • Проблема. Код, написанный для Geocoding API версии 3, не работает с ответами REST версии 4. В версии 4 используются имена полей в формате lowerCamelCase (addressComponents, а не address_components), удалены status и error_message, а из GeocodePlace возвращается один корневой объект вместо массива results. Решение. Проверьте коды статуса HTTP и тела ошибок в вызовах REST v4, прочитайте поля в нижнем верблюжьем регистре (addressComponents, postalAddress) и обратите внимание, что в ответах gRPC по-прежнему используется змеиный регистр. Подробнее: /maps/documentation/geocoding/geocoding-v4-migrate.

Geocoding API: устаревшие и не поддерживаемые функции

  • Гиперлокальные данные Geocoding API v3 (extra_computations: BUILDING_AND_ENTRANCES, NAVIGATION_POINTS, GROUNDS; поля ответа buildings.entrances, navigation_points, buildings.building_outlines, grounds): поддержка прекращена 13 августа 2025 г. Замена: метод SearchDestinations Geocoding API v4 (POST /v4/geocode/destinations). Ознакомьтесь с руководством по переносу.

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

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