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

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

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

Этот 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 v4 поддерживает 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 to sublocality_level_5 . Каждый уровень населенного пункта является гражданской сущностью. Большие числа указывают на меньшую географическую область.
    neighborhood Названный район.
    premise Имеющее название место, обычно здание или группа зданий с общим названием.
    subpremise Адресуемая сущность, расположенная ниже уровня помещения, например, квартира, блок или апартаменты.
    plus_code Кодированная ссылка на местоположение, полученная из широты и долготы. Плюс-коды могут использоваться в качестве замены уличных адресов в местах, где их нет (где здания не пронумерованы или улицы не названы). Подробности см. на https://plus.codes .
    postal_code Почтовый индекс, используемый для адресации почтовых отправлений внутри страны.
    natural_feature Выдающаяся природная достопримечательность.
    airport Аэропорт.
    park Парк с названием.
    point_of_interest Именованная точка интереса. Обычно такие «POI» — это известные местные объекты, которые нелегко отнести к другой категории, например, «Эмпайр-стейт-билдинг» или «Эйфелева башня».

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