Как выполнить обратное геокодирование

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

Обратное геокодирование преобразует местоположение на карте в человекочитаемый адрес. Местоположение на карте задается координатами широты и долготы.

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

Этот API возвращает различные типы адресов – от наиболее конкретного адреса до менее конкретных административных единиц, таких как районы, города, области, страны и т. д. Обычно самым первым результатом бывает наиболее точный адрес. Если вы хотите сопоставить определенный тип адреса, используйте параметр types.

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

Запрос обратного геокодирования – это HTTP-запрос GET. Местоположение можно указать в виде неструктурированной строки:

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

или в виде структурированного набора координат широты и долготы, представленных параметрами запроса:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Обычно структурированный формат используется при обработке компонентов местоположения, полученных из HTML-формы.

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

Передача неструктурированной строки местоположения

Неструктурированное местоположение – это местоположение, отформатированное как строка с разделенными запятыми координатами широты и долготы:

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?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/location/37.4225508,-122.0846338"

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

Укажите структурированное местоположение с помощью параметра запроса location типа LatLng. Объект LatLng позволяет указать широту и долготу в виде отдельных параметров запроса:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Как создать запрос с помощью 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.location — Используйте только с GeocodeLocation для обратного геокодирования.

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

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

Ответ обратного геокодирования

Обратное геокодирование возвращает объект GeocodeLocationResponse, который содержит:

  • Массив results объектов GeocodeResult, представляющих место.

    Ответы Geocoding API включают массивы types в двух основных местах в GeocodeResult:

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

    Обратное геокодирование возвращает несколько результатов в массиве results. Результаты включают не только почтовые адреса, но и любые варианты географического наименования места. Например, при геокодировании точки в Чикаго геокодированная точка может быть обозначена как почтовый адрес, как город (Чикаго), как штат (Иллинойс) или как страна (США). Для геокодера все эти элементы являются адресами. Обратное геокодирование возвращает любой из этих типов в качестве действительных результатов.

  • Поле plusCode типа PlusCode содержит код Plus Code, который наиболее точно соответствует широте и долготе в запросе. Кроме того, каждый элемент массива results содержит код Plus Code. Расстояние между декодированным кодом Plus Code и точкой запроса составляет менее 10 метров.

    Примечание. API не всегда возвращает коды Plus Code.

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

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "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"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

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

  • местоположение

    Координаты широты и долготы, для которых нужно получить ближайший человекочитаемый адрес.

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

  • languageCode

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

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

  • regionCode

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

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

  • детализация

    Один или несколько уровней детализации местоположения, указанных в виде отдельных параметров запроса, как определено в Granularity. Если вы укажете несколько параметров granularity, API вернет все адреса, соответствующие любому из уровней детализации.

    Параметр granularity не ограничивает поиск указанными уровнями детализации местоположения. Вместо этого granularity действует как фильтр, применяемый после поиска. API получает все результаты для указанного location, а затем отбрасывает те, которые не соответствуют указанным уровням детализации местоположения.

    Если указать и types, и granularity, API вернет только результаты, соответствующие обоим параметрам. Пример:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • типы

    Один или несколько типов адресов, указанных в виде отдельных параметров запроса. Возможные значения приведены в таблице Типы адресов и их компонентов на странице "Типы мест (новые)". Если вы укажете несколько параметров types, API вернет все адреса, соответствующие любому из типов.

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

    Если указать и types, и granularity, API вернет только те результаты, которые соответствуют обоим параметрам. Пример:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

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

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    Ответ: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

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