Термин геокодирование обычно относится к преобразованию удобочитаемого адреса в местоположение на карте. Процесс обратного преобразования местоположения на карте в удобочитаемый адрес известен как обратное геокодирование .
Запросы обратного геокодирования
Обязательные параметры
-
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
— используйте этот параметр, чтобы указать в ответе следующие дополнительные функции:-
ADDRESS_DESCRIPTORS
— дополнительные сведения см. в дескрипторах адресов . -
BUILDING_AND_ENTRANCES
— для получения более подробной информации см. входы и очертания зданий .
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 метров.