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

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

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

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

Этот 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 для отправки запроса.

API геокодирования версии 4 поддерживает аутентификацию OAuth 2.0 . Для использования OAuth с API геокодирования необходимо присвоить токену OAuth правильную область действия (scope). 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 для всех конечных точек API геокодирования. Эта область действия полезна на этапе разработки, но не в продакшене, поскольку это общая область, предоставляющая доступ ко всем конечным точкам.

Для получения дополнительной информации и примеров см. раздел «Использование OAuth» .

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

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

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

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

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

Необходимые параметры

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

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

Дополнительные параметры

  • languageCode

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

    • См. список поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
    • Если languageCode не указан, API по умолчанию использует en . Если вы укажете недопустимый код языка, 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/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 Кодированная координата местоположения, полученная на основе широты и долготы. Коды Plus могут использоваться в качестве замены уличных адресов в местах, где они отсутствуют (где здания не нумеруются или улицы не имеют названий). Подробнее см. https://plus.codes .
    postal_code Почтовый индекс, используемый для адресации почтовых отправлений внутри страны.
    natural_feature Выдающаяся природная особенность.
    airport Аэропорт.
    park Парк, имеющий своё название.
    point_of_interest Названная достопримечательность. Как правило, это известные местные объекты, которые сложно отнести к какой-либо другой категории, например, «Эмпайр-стейт-билдинг» или «Эйфелева башня».

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