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

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

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

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

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

  • 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 возвращает только те результаты, которые соответствуют location_type result_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 в ответе геокодирования содержит код, наиболее точно соответствующий запрошенным широте и долготе. Кроме того, массив результатов JSON в большинстве случаев содержит полный результат геокодирования с типом plus_code и адресом, содержащим код. Гарантируется, что расстояние между декодированным кодом и точкой запроса не превышает 10 метров.