Термин геокодирование обычно относится к переводу удобочитаемого адреса в местоположение на карте. Обратный процесс — преобразование местоположения на карте в удобочитаемый адрес — называется обратным геокодированием .
Обратные запросы геокодирования
Обязательные параметры
-
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 метров.