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

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

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

Идентификатор места однозначно идентифицирует его в базе данных Google Places и на Google Картах. Получите идентификаторы мест, когда вы геокодируете адрес. Идентификатор места также можно получить из многих других API, например Place Details (New), Text Search (New) и Nearby Search (New).

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

Запрос геокодирования места – это 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. Подробнее о типах мест в таблицах A и B…
  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"
}

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