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-backend.googleapis.com. - Аутентификация: ключ API, OAuth 2.0, сервисный аккаунт.
- Начало работы: настройка Geocoding API
- Справочные материалы: документация по Geocoding API.
- Цены: Статистика использования и оплата Geocoding API
- Правила: Правила Geocoding API
- Примечания к выпуску: Примечания к выпуску Geocoding API
Geocoding API: сопутствующие товары
- Часто используется с: Routes API, Navigation SDK для Android, Navigation SDK для iOS.
Geocoding API: распространенные ошибки
- Проблема. Запросы
SearchDestinationsбез маски поля завершаются ошибкой. В отличие отGeocodeAddress,GeocodeLocationиGeocodePlace, маска поля обязательна. Решение. Установите заголовокX-Goog-FieldMaskили параметр$fieldsдля каждого запросаSearchDestinations. Подробнее /maps/documentation/geocoding/choose-fields… - Проблема. В v4
GeocodeAddressнет жесткого фильтра компонентов (v3components=country:US). Структурированные параметрыaddress.*объединяются в один адрес и не фильтруют результаты. В v4 также нет значения по умолчанию дляregionCode(в v3 по умолчанию использовалосьus). Решение. Фильтруйтеresultsна стороне клиента: сопоставляйтеregionCodeв верхнем регистре сpostalAddress.regionCode; сопоставляйте двухбуквенные коды административных регионов в верхнем регистре сpostalAddress.administrativeAreaиadministrative_area_level_naddressComponents(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 г. Замена: методSearchDestinationsGeocoding API v4 (POST /v4/geocode/destinations). Ознакомьтесь с руководством по переносу.
Что можно делать с помощью Geocoding API
Ниже приведены ссылки на руководства по каждой задаче. Вы также можете сравнить возможности продуктов в Обзоре возможностей.
- Получать географические координаты (широту/долготу) по адресу (геокодирование).
- Получать адрес по координатам широты и долготы (обратное геокодирование).
- Ограничить запрос геокодирования, чтобы возвращались результаты в пределах определенной области просмотра. Примечание. В Geocoding API версии 4 параметр locationBias смещает результаты в сторону указанной области просмотра, а не строго ограничивает их.
- Ограничьте запрос геокодирования или обратного геокодирования, чтобы возвращались только результаты в пределах определенного региона, страны или почтового индекса. Примечание. В Geocoding API версии 4 параметр regionCode позволяет отдавать приоритет результатам из указанного региона CLDR, а не строго ограничивать их. О фильтрации по компонентам для устаревшей версии 3 по стране или почтовому индексу читайте на странице https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- Ограничьте запрос обратного геокодирования, чтобы возвращались результаты только для указанных типов адресов. Примечание. В Geocoding API версии 4 параметр types фильтрует возвращенные результаты обратного геокодирования по типу адреса после поиска, а не ограничивает базовый поиск.
- Возвращает информацию о близости к ориентирам или областям для адреса.
- Возвращает информацию о близости к ориентирам или областям для набора координат широты/долготы.
- Возвращает информацию о близости к ориентирам или областям для идентификатора места Google.
- Возвращает адрес для идентификатора места Google.
- Возвращает координаты широты и долготы контура здания по адресу.
- Возвращать координаты широты и долготы контура здания по набору координат широты и долготы.
- Возвращает координаты широты и долготы контура здания по идентификатору места Google.
- Возвращать координаты широты и долготы входа в здание по адресу.
- Возвращать координаты широты и долготы входа в здание для набора координат широты и долготы.
- Возвращает координаты широты и долготы входа в здание по идентификатору места Google.