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

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

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

Требуемые параметры

  • 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 to sublocality_level_5 . Каждый уровень населенного пункта является гражданской сущностью. Большие числа указывают на меньшую географическую область.
    neighborhood Названный район.
    premise Имеющее название место, обычно здание или группа зданий с общим названием.
    subpremise Адресуемая сущность, расположенная ниже уровня помещения, например, квартира, блок или апартаменты.
    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

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

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

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

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

Поле "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 метров.