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

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

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

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

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

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

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

  • language — язык, на котором возвращаются результаты.
    • См . список поддерживаемых языков . Google часто обновляет поддерживаемые языки, поэтому этот список может быть неполным.
    • Если language не указан, геокодер пытается использовать предпочтительный язык, указанный в заголовке Accept-Language , или родной язык домена, из которого отправлен запрос.
    • Геокодер делает все возможное, чтобы предоставить адрес, который будет удобен для чтения как пользователем, так и местными жителями. Для достижения этой цели он возвращает адреса на местном языке, транслитерированные в сценарий, который при необходимости читается пользователем, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, выбранном из первого компонента.
    • Если имя недоступно на предпочитаемом языке, геокодер использует наиболее близкое совпадение.
  • region — код региона, указанный в виде двухсимвольного значения ccTLD («домен верхнего уровня»). Параметр также может влиять на результаты в соответствии с действующим законодательством.
  • result_type — Фильтр одного или нескольких типов адресов, разделенных вертикальной чертой ( | ). Если параметр содержит несколько типов адресов, API возвращает все адреса, соответствующие любому из типов. Примечание об обработке: параметр result_type не ограничивает поиск указанными типами адресов. Скорее, result_type действует как фильтр после поиска: API извлекает все результаты для указанного latlng , затем отбрасывает те результаты, которые не соответствуют указанным типам адресов. Поддерживаются следующие значения:
    • street_address указывает точный адрес.
    • route указывает именованный маршрут (например, «US 101»).
    • intersection указывает на крупный перекресток, обычно двух основных дорог.
    • political указывает на политическую сущность. Обычно этот тип обозначает полигон какой-либо гражданской администрации.
    • country указывает национальное политическое образование и обычно является типом высшего порядка, возвращаемым геокодером.
    • administrative_area_level_1 указывает гражданское лицо первого порядка ниже уровня страны. В Соединенных Штатах такими административными уровнями являются штаты. Не все страны демонстрируют эти административные уровни. В большинстве случаев короткие названия административной_области_уровня_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 указывает на именованную достопримечательность. Как правило, эти «POI» представляют собой известные местные объекты, которые нелегко вписать в другую категорию, например «Эмпайр-Стейт-Билдинг» или «Эйфелева башня».
  • 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 в ответе на геокодирование содержит код плюса, который наилучшим образом соответствует запрашиваемой широте и долготе. Кроме того, массив результатов JSON в большинстве случаев содержит полный результат геокодирования с типом plus_code и адресом, содержащим код плюса. Расстояние между декодированным плюс-кодом и точкой запроса гарантированно не превышает 10 метров.