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

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

Термин геокодирование обычно обозначает преобразование человекочитаемого адреса в местоположение на карте. Процесс, заключающийся в преобразовании точки на карте в человекочитаемый адрес, известен как обратное геокодирование.

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

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

  • 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 Код местоположения на основе широты и долготы. Коды Plus Code можно использовать в качестве замены почтовым адресам там, где эти адреса не существуют (здания не пронумерованы или улицам не присвоены названия). Подробную информацию можно найти на сайте https://plus.codes.
    postal_code Почтовый округ (соответствует почтовому индексу).
    natural_feature Заметный природный объект.
    airport Аэропорт.
    park Парк, имеющий название.
    point_of_interest Объект инфраструктуры, имеющий название. Как правило, эти POI представляют собой крупные местные объекты, которые сложно отнести к другой категории, например "Эмпайр-стейт-билдинг" или "Эйфелева башня".

    Пустой список типов указывает, что для того или иного элемента адреса нет известных типов, например 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" в объекте ответа геокодирования содержит статус запроса и может содержать сведения для отладки, которые помогут вам выяснить, почему обратное геокодирование не работает. Поле "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

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