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

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

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

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

Запросы геокодирования мест

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

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

где PLACE_ID – идентификатор интересующего места.

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

https://geocode.googleapis.com/v4/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/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

Как отправить запрос с помощью OAuth

Geocoding API версии 4 поддерживает OAuth 2.0 для аутентификации. Чтобы использовать OAuth с Geocoding API, токену OAuth должна быть назначена правильная область действия. Geocoding API поддерживает следующие области действия для геокодирования мест:

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

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

Дополнительную информацию и примеры можно найти в статье Как использовать OAuth.

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

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

Ответы Geocoding API содержат массивы types в двух основных местах GeocodeResult:

  1. GeocodeResult.types – массив, указывающий общий тип или типы результата. Возможные значения берутся из типов мест, используемых Places API. Подробнее о таблицах А и Б с типами мест…
  2. GeocodeResult.addressComponents[].types: каждый компонент адреса имеет массив types, указывающий тип этой части адреса. Эти значения взяты из таблицы Типы адресов и их компонентов, которая используется в Places API.

Полный объект 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, возвращаемый Roads API, чтобы получить адрес фиксированной точки. Подробнее об идентификаторах мест…

Необязательные параметры

  • languageCode

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

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

  • regionCode

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

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

  • FieldMask

    Создайте маску поля ответа, чтобы указать, какие поля должны возвращаться в ответе. Передайте маску поля ответа методу, используя параметр URL $fields или fields либо заголовок HTTP X-Goog-FieldMask. Например, приведенный ниже запрос вернет только поле formattedAddress.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    Ответ: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

    Подробнее о том, как выбрать поля, которые нужно вернуть…