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

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

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

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

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

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

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

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 для обратного геокодирования.

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

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

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

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

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

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

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

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

  • Поле plusCode типа PlusCode содержит код Plus Code, который наиболее точно соответствует широте и долготе в запросе. Кроме того, каждый элемент массива results содержит плюс-код. Расстояние между декодированным кодом 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"
    },
    ...
  ]
}

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