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

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

Термин «геокодирование» обычно относится к преобразованию адреса, понятного человеку, в местоположение на карте. Обратный процесс — преобразование местоположения на карте в адрес, понятный человеку, — называется обратным геокодированием .

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

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

  • latlng — координаты широты и долготы, указывающие местоположение, для которого требуется получить ближайший понятный человеку адрес.
  • key — API-ключ вашего приложения. Этот ключ идентифицирует ваше приложение для управления квотами. Узнайте, как получить ключ .

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

Это необязательные параметры, которые можно включить в запрос обратного геокодирования:

  • language — язык, на котором будут возвращаться результаты.
    • Ознакомьтесь со списком поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
    • Если language не указан, геокодер попытается использовать предпочитаемый язык, указанный в заголовке Accept-Language , или родной язык домена, с которого отправлен запрос.
    • Геокодер делает всё возможное, чтобы предоставить адрес, понятный как пользователю, так и местным жителям. Для этого он возвращает адреса на местном языке, при необходимости транслитерируя их в удобный для пользователя язык с учётом выбранного языка. Все остальные адреса возвращаются на выбранном языке. Все компоненты адреса возвращаются на одном языке, выбранном из первого компонента.
    • Если имя отсутствует на предпочитаемом языке, геокодер использует наиболее близкое совпадение.
  • region — код региона, указанный в виде двухсимвольного значения ccTLD («домена верхнего уровня»). Этот параметр также может влиять на результаты в соответствии с действующим законодательством.
  • result_type — фильтр по одному или нескольким типам адресов, разделённым вертикальной чертой ( | ). Если параметр содержит несколько типов адресов, API возвращает все адреса, соответствующие любому из них. Примечание об обработке: параметр result_type не ограничивает поиск указанными типами адресов. Вместо этого result_type действует как фильтр, применяемый после поиска: API извлекает все результаты для указанного latlng , а затем отбрасывает те, которые не соответствуют указанному типу адресов. Поддерживаются следующие значения:

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

    Массив 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 во Франции).

  • location_type — фильтр по одному или нескольким типам местоположений, разделённым вертикальной чертой ( | ). Если параметр содержит несколько типов местоположений, API возвращает все адреса, соответствующие любому из этих типов. Примечание об обработке: параметр location_type не ограничивает поиск указанными типами местоположений. Вместо этого location_type действует как фильтр после поиска: API извлекает все результаты для указанного значения latlng , а затем отбрасывает те, которые не соответствуют указанным типам местоположений. Поддерживаются следующие значения:
    • "ROOFTOP" возвращает только те адреса, для которых у Google есть точная информация о местоположении вплоть до адреса улицы.
    • "RANGE_INTERPOLATED" возвращает только адреса, которые представляют собой приблизительное значение (обычно на дороге), интерполированное между двумя точными точками (например, перекрёстками). Интерполированный диапазон обычно указывает на то, что геокоды крыш недоступны для данного адреса.
    • "GEOMETRIC_CENTER" возвращает только геометрические центры местоположения, такого как полилиния (например, улица) или многоугольник (регион).
    • "APPROXIMATE" возвращает только те адреса, которые характеризуются как приблизительные.
  • extra_computations — Используйте этот параметр, чтобы указать следующие дополнительные функции в ответе: Чтобы включить несколько таких функций для одного запроса API, включите параметр extra_computations в запрос для каждой функции, например: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Если присутствуют оба фильтра result_type и location_type , API возвращает только те результаты, которые соответствуют значениям result_type и location_type . Если ни одно из значений фильтра не подходит, API возвращает ZERO_RESULTS .

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

Следующий запрос содержит значение широты/долготы для местоположения в Бруклине:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Приведенный выше запрос возвращает следующий результат:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

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

Обратный геокодер сопоставляет политические единицы (страны, провинции, города и районы), уличные адреса и почтовые индексы.

Полный список значений formatted_address , возвращенных предыдущим запросом, показан ниже.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

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

Обратное геокодирование с фильтрацией по типу

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

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Примечание: эти фильтры действительны только для обратного геокодирования.

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

Формат ответа обратного геокодирования совпадает с форматом ответа геокодирования. См. раздел Ответы геокодирования . Ниже приведены коды статуса, возможные в ответе обратного геокодирования.

Коды статуса обратного геокодирования

Поле "status" в объекте ответа Geocoding содержит статус запроса и может содержать отладочную информацию, которая поможет вам определить причину сбоя обратного геокодирования. Поле "status" может содержать следующие значения:

  • "OK" означает, что ошибок не произошло и был возвращен по крайней мере один адрес.
  • "ZERO_RESULTS" означает, что обратное геокодирование прошло успешно, но не вернуло результатов. Это может произойти, если геокодеру были переданы координаты latlng в удалённом местоположении.
  • "OVER_QUERY_LIMIT" означает, что вы превысили свою квоту.
  • "REQUEST_DENIED" означает, что запрос был отклонён. Возможно, это связано с тем, что запрос включает параметр result_type или location_type , но не включает ключ API.
  • "INVALID_REQUEST" обычно указывает на одно из следующих:
    • Запрос ( address , components или latlng ) отсутствует.
    • Указан неверный result_type или location_type .
  • "UNKNOWN_ERROR" означает, что запрос не удалось обработать из-за ошибки сервера. Запрос может быть выполнен успешно, если вы повторите попытку.

Обратное геокодирование плюс коды

Поле plus_code в ответе Geocoding содержит плюс-код, который наилучшим образом соответствует запрошенным широте и долготе. Кроме того, массив результатов JSON в большинстве случаев содержит полный результат Geocoding с типом plus_code и адресом, содержащим плюс-код. Расстояние между декодированным плюс-кодом и запрошенной точкой гарантированно не превышает 10 метров.