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

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

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

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

Этот API возвращает различные типы адресов: от самых точных уличных адресов до менее точных политических образований, таких как районы, города, округа и штаты. Самый точный адрес обычно оказывается первым результатом. Если вам нужен адрес определённого типа, используйте параметр types .

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

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

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

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

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

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

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

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

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

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

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

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

https://geocode.googleapis.com/v4beta/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 — Используйте со всеми конечными точками API геокодирования.
  • https://www.googleapis.com/auth/maps-platform.geocode.location — Используйте только с GeocodeLocation для обратного геокодирования.

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

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

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

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

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

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

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

Полный объект 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"
  }
}

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

  • расположение

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

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

  • код_языка

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

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

  • Код региона

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

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

  • зернистость

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

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

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

    https://geocode.googleapis.com/v4beta/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/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

    Поддерживаются следующие значения:

    Типы адресов и типы компонентов адреса

    Массив types в теле GeocodeResult ответа указывает тип адреса . Примеры типов адреса включают почтовый адрес, страну или политическое образование. Массив types в поле AddressComponents тела GeocodeResult указывает тип каждой части адреса. Примеры включают номер дома или страну.

    Адреса могут иметь несколько типов. Эти типы можно считать «тегами». Например, многие города имеют теги political и locality типов.

    Следующие типы поддерживаются и возвращаются как в массивах типов адреса, так и в массивах типов компонентов адреса:

    Тип адреса Описание
    street_address Точный почтовый адрес.
    route Именованный маршрут (например, «US 101»).
    intersection Крупный перекрёсток, обычно двух крупных дорог.
    political Политическая единица. Обычно этот тип обозначает полигон какой-либо гражданской администрации.
    country Национальная политическая единица, обычно имеющая тип наивысшего порядка, возвращаемый геокодером.
    administrative_area_level_1 Гражданская единица первого порядка, ниже уровня страны. В Соединенных Штатах такими административными уровнями являются штаты. Не во всех странах существуют такие административные уровни. В большинстве случаев краткие названия administrative_area_level_1 будут точно соответствовать обозначениям подразделений ISO 3166-2 и другим широко распространенным спискам; однако это не гарантируется, поскольку наши результаты геокодирования основаны на различных сигналах и данных о местоположении.
    administrative_area_level_2 Гражданская единица второго порядка, ниже уровня страны. В Соединённых Штатах такими административными уровнями являются округа. Не во всех странах существуют такие административные уровни.
    administrative_area_level_3 Гражданская единица третьего порядка, ниже уровня страны. Этот тип указывает на незначительное административное деление. Не во всех странах существуют такие административные уровни.
    administrative_area_level_4 Гражданская единица четвёртого порядка, ниже уровня страны. Этот тип указывает на незначительное административное деление. Не во всех странах существуют такие административные уровни.
    administrative_area_level_5 Гражданская единица пятого уровня, ниже уровня страны. Этот тип указывает на незначительное административное деление. Не во всех странах существуют такие административные уровни.
    administrative_area_level_6 Гражданская единица шестого уровня, ниже уровня страны. Этот тип указывает на незначительное административное деление. Не во всех странах существуют такие административные уровни.
    administrative_area_level_7 Гражданская единица седьмого уровня, ниже уровня страны. Этот тип указывает на незначительное административное деление. Не во всех странах существуют такие административные уровни.
    colloquial_area Общеупотребительное альтернативное название сущности.
    locality Инкорпорированная городская или поселковая политическая единица.
    sublocality Гражданская единица первого порядка, нижестоящая над населённым пунктом. Для некоторых населённых пунктов может иметь один из дополнительных типов: sublocality_level_1 – sublocality_level_5 . Каждый уровень населённого пункта является гражданской единицей. Большие числа указывают на меньшую географическую область.
    neighborhood Район с названием.
    premise Имеющее название место, обычно здание или группа зданий с общим названием.
    subpremise Адресуемая сущность, расположенная ниже уровня помещения, например квартира, блок или апартаменты.
    plus_code Код местоположения, полученный из широты и долготы. Плюс-коды могут использоваться для замены уличных адресов в местах, где их нет (где дома не пронумерованы или улицы не имеют названий). Подробнее см. https://plus.codes .
    postal_code Почтовый индекс, используемый для адресации почтовых отправлений внутри страны.
    natural_feature Выдающаяся природная достопримечательность.
    airport Аэропорт.
    park Парк с названием.
    point_of_interest Имеющаяся точка интереса. Обычно такие «точки интереса» представляют собой известные местные объекты, которые сложно отнести к другой категории, например, «Эмпайр-стейт-билдинг» или «Эйфелева башня».

    Пустой список типов указывает на то, что для конкретного компонента адреса не существует известных типов (например, Lieu-dit во Франции).