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

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

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

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

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

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

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

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

Если присутствуют оба фильтра 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 в большинстве случаев содержит полный результат Geocoding с типом plus_code и адрес, содержащий код plus. Расстояние между расшифрованным плюс-кодом и точкой запроса гарантированно не превышает 10 метров.