Геокодирование места

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

Геокодирование мест позволяет получить адрес по идентификатору места .

Идентификаторы мест однозначно определяют местоположение в базе данных Google Places и на Google Maps. Получить идентификаторы мест можно при геокодировании адреса . Также идентификатор места можно получить из многих других API, таких как «Подробная информация о месте» (новая функция) , «Текстовый поиск» (новая функция) и «Поиск поблизости» (новая функция) .

Отправляйте запросы на геокодирование

Запрос на геокодирование местоположения представляет собой HTTP GET-запрос следующего вида:

https://geocode.googleapis.com/v4beta/geocode/places/PLACE_ID

Где PLACE_ID содержит идентификатор интересующего местоположения.

Все остальные параметры передавайте в качестве параметров URL или, для таких параметров, как ключ API или маска поля, в заголовках GET-запроса. Например:

https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?key=API_KEY

Или в команде curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

Используйте OAuth для отправки запроса.

API геокодирования версии 4 поддерживает аутентификацию OAuth 2.0 . Для использования OAuth с API геокодирования необходимо присвоить токену OAuth правильную область действия (scope). API геокодирования поддерживает следующие области действия для использования с геокодированием мест:

  • https://www.googleapis.com/auth/maps-platform.geocode — Использовать со всеми конечными точками API геокодирования.
  • https://www.googleapis.com/auth/maps-platform.geocode.place — Используйте только с GeocodePlace для геокодирования мест.

Кроме того, вы можете использовать общую область действия https://www.googleapis.com/auth/cloud-platform для всех конечных точек API геокодирования. Эта область действия полезна на этапе разработки, но не в продакшене, поскольку это общая область, предоставляющая доступ ко всем конечным точкам.

Для получения дополнительной информации и примеров см. раздел «Использование OAuth» .

Разместите ответы с геокодированием

Функция геокодирования мест возвращает объект GeocodeResult , представляющий место, соответствующее идентификатору места.

Полный JSON-объект имеет следующий вид:

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "addressComponents": [
    {
      "longText": "1600",
      "shortText": "1600",
      "types": [
        "street_number"
      ]
    },
    {
      "longText": "Amphitheatre Parkway",
      "shortText": "Amphitheatre Pkwy",
      "types": [
        "route"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Mountain View",
      "shortText": "Mountain View",
      "types": [
        "locality",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "Santa Clara County",
      "shortText": "Santa Clara County",
      "types": [
        "administrative_area_level_2",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "California",
      "shortText": "CA",
      "types": [
        "administrative_area_level_1",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "United States",
      "shortText": "US",
      "types": [
        "country",
        "political"
      ],
      "languageCode": "en"
    },
    {
      "longText": "94043",
      "shortText": "94043",
      "types": [
        "postal_code"
      ]
    }
  ],
  "types": [
    "establishment",
    "point_of_interest"
  ]
}

Необходимые параметры

  • place — Идентификатор места, для которого вы хотите получить удобочитаемый адрес. Идентификатор места — это уникальный идентификатор, который можно использовать с другими API Google. Например, вы можете использовать placeID возвращаемый API дорог, чтобы получить адрес для точки привязки. Для получения дополнительной информации об идентификаторах мест см. раздел « Идентификаторы мест» .

Дополнительные параметры

  • languageCode

    Язык, на котором будут возвращаться результаты.

    • См. список поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
    • Если languageCode не указан, API по умолчанию использует en . Если вы укажете недопустимый код языка, API вернет ошибку INVALID_ARGUMENT .
    • API делает все возможное, чтобы предоставить уличный адрес, понятный как пользователю, так и местным жителям. Для достижения этой цели он возвращает уличные адреса на местном языке, при необходимости транслитерированные в письменность, понятную пользователю, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на одном языке, который выбирается из первого компонента.
    • Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
    • Предпочитаемый язык оказывает незначительное влияние на набор результатов, которые API выбирает для возврата, и на порядок их возврата. Геокодер по-разному интерпретирует сокращения в зависимости от языка, например, сокращения для типов улиц или синонимы, которые могут быть допустимы в одном языке, но не в другом.

  • regionCode

    Региональный код представляет собой двухсимвольное значение кода CLDR . Значение по умолчанию отсутствует. Большинство кодов CLDR идентичны кодам ISO 3166-1.

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