Переход с версии геокодирования v3 на v4

Разработчики из Европейской экономической зоны (ЕЭЗ)

Если ваш платежный адрес находится в Европейской экономической зоне, то с 8 июля 2025 года к использованию вами Услуг будут применяться Условия предоставления услуг платформы Google Maps для стран ЕЭЗ . Функциональность различается в зависимости от региона. Подробнее .

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

Вы можете использовать свои существующие ключи API с новыми конечными точками версии 4. Однако, если вы запросили увеличение квоты для версии 3 API, вам необходимо запросить увеличение квоты и для новых API версии 4. Для пользователей JavaScript миграция не предусмотрена.

Примечание: В режиме предварительного просмотра количество запросов к методам Geocoding API v4 ограничено 25 запросами в секунду (QPS). Информацию о запросе увеличения квоты см. в разделе «Просмотр и управление квотами» и выберите Geocoding API в качестве службы.

Переход с v3 Forward Geocoding

Если вы используете геокодирование для определения местоположения адресов, вам следует перейти на конечную точку геокодирования адресов версии 4, которая принимает GET-запросы.

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

Внимание: Во всех конечных точках версии 4 имена полей форматируются с использованием нижнего регистра camel case (например, addressComponents), в отличие от конечных точек версии 3, где использовался регистр snake case (например, address_components). Ответы RPC продолжают использовать регистр snake case в версии 4, как и в версии 3.

Запрос на изменение параметров

Параметр v3	Параметр v4	Примечания
address , components	address	Неструктурированный адрес ( address v3) теперь передается в пути URL. Фильтры компонентов ( components v3) теперь передаются в качестве параметров запроса address.*
bounds	locationBias.rectangle	Переименовано; структура изменена на объект.
language	languageCode	Переименовано.
region	regionCode	Переименовано.
extra_computations	Удаленный

Изменения в поле ответа

поле v3	поле v4	Примечания
status , error_message	Удаленный	В версии v4 используются коды состояния HTTP и тела ошибок .
results.address_components.long_name / results.address_components.short_name	results.addressComponents.longText / results.addressComponents.shortText	Переименовано.
results.geometry.location_type	results.granularity	Переименовано.
results.geometry.location	results.location	Названия полей: lat / lng -> latitude / longitude .
results.geometry.viewport	results.viewport	Названия полей: northeast / southwest -> high / low .
results.postcode_localities	results.postalCodeLocalities	Переименовано. Теперь возвращается для одного или нескольких населенных пунктов (требуется v3 >1).
results.partial_match	Удаленный
Новый	results.addressComponents.languageCode	Язык конкретного компонента адреса.
Новый	results.bounds	Явные границы с использованием high / low .
Новый	results.place	Название ресурса для данного места.
Новый	results.postalAddress	Структурированный объект PostalAddress .

Переход с версии 3 обратного геокодирования

Если вы используете обратное геокодирование для преобразования координат в адреса, вам следует перейти на конечную точку обратного геокодирования местоположения версии 4, которая принимает GET-запрос.

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

Внимание: Во всех конечных точках версии 4 имена полей форматируются с использованием нижнего регистра camel case (например, addressComponents), в отличие от конечных точек версии 3, где использовался регистр snake case (например, address_components). Ответы RPC продолжают использовать регистр snake case в версии 4, как и в версии 3.

Запрос на изменение параметров

Параметр v3	Параметр v4	Примечания
language	languageCode	Переименовано.
region	regionCode	Переименовано.
result_type	types	Переименовано; используются повторяющиеся параметры запроса.
location_type	granularity	Переименовано; используются повторяющиеся параметры запроса.
extra_computations	Удаленный

Изменения в поле ответа

поле v3	поле v4	Примечания
status , error_message	Удаленный	В версии v4 используются коды состояния HTTP и тела ошибок .
results.address_components.long_name / results.address_components.short_name	results.addressComponents.longText / results.addressComponents.shortText	Переименовано.
results.geometry.location_type	results.granularity	Переименовано.
results.geometry.location	results.location	Названия полей: lat / lng -> latitude / longitude .
results.geometry.viewport	results.viewport	Названия полей: northeast / southwest -> high / low .
Новый	results.addressComponents.languageCode	Язык конкретного компонента адреса.
Новый	results.bounds	Явные границы с использованием high / low .
Новый	results.place	Название ресурса для данного места.
Новый	results.postalAddress	Структурированный объект PostalAddress .

Перенос с версии 3 на геокодирование местоположения

Если вы используете place_id для получения адреса для конкретного идентификатора места с помощью Geocoding v3, вам необходимо перейти на конечную точку геокодирования мест версии 4, которая принимает GET-запрос.

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

Внимание: Во всех конечных точках версии 4 имена полей форматируются с использованием нижнего регистра camel case (например, addressComponents), в отличие от конечных точек версии 3, где использовался регистр snake case (например, address_components). Ответы RPC продолжают использовать регистр snake case в версии 4, как и в версии 3.

Запрос на изменение параметров

Параметр v3	Параметр v4	Примечания
place_id	place поле в протокол запроса	Идентификатор места теперь передается в качестве параметра пути places/{place} , например: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw . Это соответствует полю place в базовом запросе.
language	languageCode	Переименовано.
region	regionCode	Переименовано.

Изменения в поле ответа

поле v3	поле v4	Примечания
status , error_message	Удаленный	В версии v4 используются коды состояния HTTP и тела ошибок .
results	(корень)	Версия v4 возвращает один объект результата, а не массив results .
results.address_components.long_name / results.address_components.short_name	addressComponents.longText / addressComponents.shortText	Переименовано.
results.geometry.location_type	granularity	Переименовано.
results.geometry.location	location	Названия полей: lat / lng -> latitude / longitude .
results.geometry.viewport	viewport	Названия полей: northeast / southwest -> high / low .
results.postcode_localities	postalCodeLocalities	Переименовано. Теперь возвращается для одного или нескольких населенных пунктов (требуется v3 >1).
Новый	addressComponents.languageCode	Язык конкретного компонента адреса.
Новый	bounds	Явные границы с использованием high / low .
Новый	place	Название ресурса для данного места.
Новый	postalAddress	Структурированный объект PostalAddress .

Переход от геокодирования гиперлокальных данных к геолокационным данным о местоположении.

Следующие функции API геокодирования версии 3 заменяются конечной точкой SearchDestinations API геокодирования версии 4:

• Входы
• Навигационные точки
• Контуры здания
• Территория

Если вы использовали API геокодирования версии 3 для получения указанных выше данных, воспользуйтесь этим документом, чтобы перейти к использованию конечной точки SearchDestinations. В этом документе объясняется, где в ответе API SearchDestinations можно найти эти данные, а также описываются различия в представлении этих данных в ответах API между API геокодирования версии 3 и конечной точкой SearchDestinations API геокодирования версии 4.

Входы

To get the entrances associated with a destination , use the field destination.entrances .

Обратите внимание, что формат entrance немного отличается от формата входа в API геокодирования версии 3. Каждый вход в destination.entrances имеет следующие поля:

• displayName — это новое необязательное поле, в котором будет отображаться удобочитаемое название входа, например, «Ворота B».
• location — это местоположение типа LatLng , которое отличается от формата, используемого в API геокодирования версии 3.
• tags — это то же самое, что и поле tags входов из API геокодирования версии 3.
• place — аналогично полю buildingPlaceId входов в API геокодирования версии 3. Однако идентификатор места в этом поле может относиться к любому типу места, а не обязательно только к зданию.

Навигационные точки

Чтобы получить точки навигации, связанные с destination , используйте поле destination.navigationPoints .

Обратите внимание, что формат navigationPoint немного отличается от формата точек навигации в Geocoding API v3 . Каждая точка навигации в destination.navigationPoints имеет следующие поля:

• displayName — это новое необязательное поле, которое будет содержать удобочитаемое имя для точки навигации, например, "5th Ave".
• location — это местоположение типа LatLng , которое отличается от формата, используемого в API геокодирования версии 3.
• travelModes — это поле аналогично полю restrictedTravelModes в точках навигации из API геокодирования версии 3. Возможные значения перечисления те же, единственное отличие заключается в том, что теперь это поле представляет собой допустимые способы передвижения для точки навигации, а не запрещенные способы передвижения.
• usage — это новое поле, содержащее варианты использования, поддерживаемые точкой навигации. Обратите внимание, что для большинства точек навигации будет указано «Использование UNKNOWN , но это не обязательно означает, что использование точки навигации каким-либо образом ограничено.

Контуры здания

Чтобы получить контуры зданий, связанных с destination , следует использовать поле displayPolygon объектов placeView в destination , представляющих здания. Для каждого placeView можно проверить, является ли он зданием, с помощью поля placeView.structureType . Если тип структуры — BUILDING , то контур можно получить из поля placeView.displayPolygon . placeView также будет содержать дополнительные поля для здания, которых не было в API геокодирования версии 3.

Примечание: Ищете только полигон здания в определенном месте? Вы можете использовать параметр placeFilter в своем запросе, чтобы сузить результаты. Чтобы вернуть только здания, установите structureType в значение "BUILDING" в параметре placeFilter . Если получение полигона является вашим приоритетом (даже для мест без точных адресов), установите addressability в значение "ANY" в placeFilter , чтобы вернуть наиболее точный доступный полигон.

Пример

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

Объект placeView в destination может представлять здание, отображая его в следующих полях:

• destination.primary - это основное местоположение для пункта назначения.
• destination.containingPlaces — это повторяющееся поле, которое может содержать более крупные объекты, «содержащие» основное место. Например, если основное место является subpremise , containingPlaces обычно будет содержать placeView , представляющий здание.
• destination.subDestinations — это повторяющееся поле, которое может содержать подпункты основного места. Например, отдельные квартиры в здании. Обычно это поле не содержит placeView , представляющего здание.

Обратите внимание, что формат placeView.displayPolygon соответствует формату контуров зданий в Geocoding API v3 , который представляет собой формат GeoJSON, использующий формат RFC 7946 .

Территория

Аналогично контурам зданий, чтобы получить информацию о территории, связанной с destination , следует использовать поле displayPolygon объектов placeView в destination , которые представляют собой территорию. Для каждого placeView можно проверить, является ли он территорией, с помощью поля placeView.structureType . Если тип структуры — GROUNDS , вы можете получить контур из поля placeView.displayPolygon . placeView также будет содержать дополнительные поля для территории, которых не было в API геокодирования версии 3.

destination placeView может представлять собой объект, содержащий информацию о территории, в следующих полях:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

Обратите внимание, что формат placeView.displayPolygon соответствует формату контура территории в Geocoding API v3 , который представляет собой формат GeoJSON, использующий формат RFC 7946 .

Используйте маску поля для запроса этих функций.

Для доступа к конечной точке SearchDestinations требуется маска поля, как поясняется в разделе «Выбор полей для возврата» . Маску поля можно установить на * для возврата всех полей или указать конкретные поля, которые вы хотите получить. Например, следующий API-запрос устанавливает маску поля для получения всех полей, необходимых для получения информации о входах, точках навигации, контурах зданий и территории пункта назначения:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations