Запрос
Запрос API геокодирования имеет следующую форму:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
где outputFormat может иметь одно из следующих значений:
-
json(рекомендуется) указывает вывод в формате JavaScript Object Notation (JSON); или -
xmlуказывает вывод в формате XML
Требуется HTTPS.
Некоторые параметры обязательны, а некоторые необязательны. Как это принято в URL, параметры разделяются с помощью символа амперсанда ( & ).
Остальная часть этой страницы описывает геокодирование и обратное геокодирование по отдельности, поскольку для каждого типа запроса доступны разные параметры.
Параметры геокодирования (поиск широты/долготы)
Обязательные параметры в запросе геокодирования:
-
key— API-ключ вашего приложения. Этот ключ идентифицирует ваше приложение для целей управления квотами. Узнайте, как получить ключ . В запросе необходимо указать либо
address, либоcomponents, либо и то, и другое:-
address— почтовый адрес или плюс-код , который вы хотите геокодировать. Укажите адреса в соответствии с форматом, используемым национальной почтовой службой соответствующей страны. Следует избегать дополнительных элементов адреса, таких как названия компаний и номера подразделений, офисов или этажей. Элементы почтового адреса должны быть разделены пробелами (здесь показано как URL-экранированные до%20):address=24%20Sussex%20Drive%20Ottawa%20ON
%2B, а пробелы — до%20):- глобальный код представляет собой 4-символьный код города и 6-символьный или более длинный локальный код (849VCWC8+R9 =
849VCWC8%2BR9). - Составной код — это локальный код длиной 6 или более символов с явным указанием местоположения (CWC8+R9 Маунтин-Вью, Калифорния, США — это
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- глобальный код представляет собой 4-символьный код города и 6-символьный или более длинный локальный код (849VCWC8+R9 =
-
components— Фильтр компонентов с элементами, разделенными вертикальной чертой (|). Фильтр компонентов также принимается как необязательный параметр, если указанaddress. Каждый элемент в фильтре компонентов состоит из парыcomponent:valueи полностью ограничивает результаты геокодера. Подробнее о фильтрации компонентов см. ниже.
-
Дополнительные рекомендации см. в разделе часто задаваемых вопросов .
Необязательные параметры в запросе геокодирования:
-
bounds— Ограничивающий блок области просмотра, в пределах которого результаты геокодирования будут смещены более заметно. Этот параметр будет влиять только на результаты геокодера, а не полностью их ограничивать. (Дополнительную информацию см. в разделе Viewport Biasing ниже.) -
language— язык, на котором будут возвращаться результаты.- См. список поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
- Если
languageне указан, геокодер пытается использовать предпочтительный язык, указанный в заголовкеAccept-Language, или родной язык домена, с которого отправлен запрос. - Геокодер делает все возможное, чтобы предоставить адрес, который будет понятен как пользователю, так и местным жителям. Для достижения этой цели он возвращает адрес на местном языке, транслитерированный в сценарий, понятный пользователю, если необходимо, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на том же языке, который выбирается из первого компонента.
- Если имя недоступно на предпочитаемом языке, геокодер использует наиболее близкое совпадение.
- Предпочтительный язык имеет небольшое влияние на набор результатов, которые API выбирает для возврата, и порядок, в котором они возвращаются. Геокодер интерпретирует аббревиатуры по-разному в зависимости от языка, например, аббревиатуры для типов улиц или синонимы, которые могут быть допустимы в одном языке, но не в другом. Например, utca и tér являются синонимами для улицы и площади соответственно в венгерском языке.
-
region— Код региона, указанный как двухсимвольное значение ccTLD («домен верхнего уровня»). Этот параметр будет влиять только на результаты геокодера, а не полностью их ограничивать. (Дополнительную информацию см. в разделе «Смещение региона» ниже.) Параметр также может влиять на результаты на основе применимого законодательства. -
components— Фильтр компонентов с элементами, разделенными вертикальной чертой (|). Фильтр компонентов требуется , если запрос не содержитaddress. Каждый элемент в фильтре компонентов состоит из парыcomponent:valueи полностью ограничивает результаты геокодера. Подробнее о фильтрации компонентов см. ниже. -
extra_computations— Используйте этот параметр, чтобы указать следующие дополнительные функции в ответе:-
ADDRESS_DESCRIPTORS— Более подробную информацию см. в дескрипторах адресов . -
BUILDING_AND_ENTRANCES— Более подробную информацию см. на схемах входов и зданий .
extra_computationsв запрос для каждой функции, например:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
-
Ответы
Ответы геокодирования возвращаются в формате, указанном флагом output в URL-запросе, или в формате JSON по умолчанию.
В этом примере API геокодирования запрашивает ответ json для запроса по адресу «1600 Amphitheatre Parkway, Mountain View, CA».
В этом запросе демонстрируется использование флага output JSON:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Этот запрос демонстрирует использование флага output XML:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Выберите вкладки ниже, чтобы увидеть примеры ответов JSON и XML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
Обратите внимание, что ответ JSON содержит два корневых элемента:
-
"status"содержит метаданные по запросу. См. коды статуса ниже. -
"results"содержит массив геокодированной адресной информации и геометрической информации.
Обычно при поиске адресов возвращается только одна запись в массиве "results" , хотя геокодер может возвращать несколько результатов, если запросы адресов неоднозначны.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Обратите внимание, что ответ XML состоит из одного <GeocodeResponse> и двух элементов верхнего уровня:
-
<status>содержит метаданные по запросу. См. коды статуса ниже. - Ноль или более элементов
<result>, каждый из которых содержит один набор геокодированной адресной информации и геометрической информации.
Ответ XML значительно длиннее ответа JSON. По этой причине мы рекомендуем вам использовать json в качестве предпочтительного выходного флага, если только ваша служба по какой-то причине не требует xml . Кроме того, обработка деревьев XML требует некоторой осторожности, поэтому вы ссылаетесь на правильные узлы и элементы. См. Parsing XML with XPath для некоторых рекомендуемых шаблонов проектирования для обработки выходных данных.
- Результаты XML помещаются в корневой элемент
<GeocodeResponse>. - JSON обозначает записи с несколькими элементами с помощью массивов множественного числа (
types), тогда как XML обозначает их с помощью нескольких единичных элементов (<type>). - Пустые элементы обозначаются через пустые массивы в JSON, но отсутствием любого такого элемента в XML. Ответ, который не генерирует никаких результатов, вернет пустой массив
resultsв JSON, но никаких элементов<result>в XML, например.
Коды статуса
Поле "status" в объекте ответа Geocoding содержит статус запроса и может содержать отладочную информацию, которая поможет вам отследить, почему геокодирование не работает. Поле "status" может содержать следующие значения:
-
"OK"означает, что ошибок не произошло; адрес был успешно проанализирован и был возвращен по крайней мере один геокод. -
"ZERO_RESULTS"указывает на то, что геокодирование прошло успешно, но не вернуло результатов. Это может произойти, если геокодеру был передан несуществующийaddress. -
OVER_DAILY_LIMITуказывает на любое из следующего:- Ключ API отсутствует или недействителен.
- В вашем аккаунте не включена функция выставления счетов.
- Превышен установленный лимит использования.
- Указанный способ оплаты больше не действителен (например, истек срок действия кредитной карты).
Чтобы узнать, как это исправить, ознакомьтесь с часто задаваемыми вопросами по Картам .
-
"OVER_QUERY_LIMIT"означает, что вы превысили свою квоту. -
"REQUEST_DENIED"означает, что ваш запрос был отклонен. -
"INVALID_REQUEST"обычно указывает на то, что запрос (address,componentsилиlatlng) отсутствует. -
"UNKNOWN_ERROR"означает, что запрос не может быть обработан из-за ошибки сервера. Запрос может быть выполнен успешно, если вы попробуете еще раз.
Сообщения об ошибках
Когда геокодер возвращает код статуса, отличный от OK , в объекте ответа Geocoding может быть дополнительное поле error_message . Это поле содержит более подробную информацию о причинах данного кода статуса.
Результаты
Когда геокодер возвращает результаты, он помещает их в массив results (JSON). Даже если геокодер не возвращает никаких результатов (например, если адрес не существует), он все равно возвращает пустой массив results . (Ответы XML состоят из нуля или более элементов <result> .)
Типичный результат содержит следующие поля:
- Массив
types[]указывает тип возвращаемого результата. Этот массив содержит набор из нуля или более тегов, идентифицирующих тип объекта, возвращаемого в результате. Например, геокод "Chicago" возвращает "locality", что указывает на то, что "Chicago" является городом, а также возвращает "political", что указывает на то, что это политическая единица. Компоненты могут иметь пустой массив типов, когда для этого компонента адреса нет известных типов. API может добавлять новые значения типов по мере необходимости. Для получения дополнительной информации см. Типы адресов и компоненты адреса . -
formatted_address— это строка, содержащая понятный человеку адрес этого местоположения.Часто этот адрес эквивалентен почтовому адресу. Обратите внимание, что некоторые страны, такие как Великобритания, не разрешают распространение настоящих почтовых адресов из-за лицензионных ограничений.
Форматированный адрес логически состоит из одного или нескольких компонентов адреса . Например, адрес «111 8th Avenue, New York, NY» состоит из следующих компонентов: «111» (номер улицы), «8th Avenue» (маршрут), «New York» (город) и «NY» (штат США).
Не анализируйте форматированный адрес программно. Вместо этого следует использовать отдельные компоненты адреса, которые ответ API включает в себя в дополнение к полю форматированного адреса.
-
address_components[]— массив, содержащий отдельные компоненты, применимые к данному адресу.Каждый компонент адреса обычно содержит следующие поля:
-
types[]— массив, указывающий тип компонента адреса. См. список поддерживаемых типов . -
long_name— полное текстовое описание или имя компонента адреса, возвращаемое геокодером. -
short_name— сокращенное текстовое имя компонента адреса, если доступно. Например, компонент адреса для штата Аляска может иметьlong_name«Alaska» иshort_name«AK» с использованием двухбуквенной почтовой аббревиатуры.
Обратите внимание на следующие факты о массиве
address_components[]:- Массив компонентов адреса может содержать больше компонентов, чем
formatted_address. - Массив не обязательно включает все политические субъекты, содержащие адрес, за исключением тех, которые включены в
formatted_address. Чтобы получить все политические субъекты, содержащие определенный адрес, следует использовать обратное геокодирование, передавая широту/долготу адреса в качестве параметра запроса. - Формат ответа не гарантирует, что останется неизменным между запросами. В частности, количество
address_componentsзависит от запрошенного адреса и может меняться со временем для одного и того же адреса. Компонент может изменить положение в массиве. Тип компонента может измениться. Определенный компонент может отсутствовать в более позднем ответе.
Для обработки массива компонентов необходимо разобрать ответ и выбрать соответствующие значения с помощью выражений. См. руководство по разбору ответа .
-
-
postcode_localities[]— массив, обозначающий до 100 населенных пунктов, содержащихся в почтовом индексе. Он присутствует только тогда, когда результатом является почтовый индекс, содержащий несколько населенных пунктов. -
geometryсодержит следующую информацию:-
locationсодержит геокодированное значение широты и долготы. Для обычного поиска адреса это поле обычно самое важное. location_typeхранит дополнительные данные об указанном местоположении. В настоящее время поддерживаются следующие значения:-
"ROOFTOP"означает, что возвращаемый результат представляет собой точный геокод, для которого у нас есть точная информация о местоположении вплоть до почтового адреса. -
"RANGE_INTERPOLATED"указывает, что возвращаемый результат отражает приближение (обычно на дороге), интерполированное между двумя точными точками (например, перекрестками). Интерполированные результаты обычно возвращаются, когда геокоды крыш недоступны для адреса улицы. -
"GEOMETRIC_CENTER"указывает, что возвращаемый результат является геометрическим центром результата, такого как полилиния (например, улица) или многоугольник (регион). -
"APPROXIMATE"указывает на то, что возвращаемый результат является приблизительным.
-
-
viewportсодержит рекомендуемый viewport для отображения возвращаемого результата, указанный как два значения широты и долготы, определяющиеsouthwestиnortheastуглы ограничивающего прямоугольника viewport. Обычно viewport используется для обрамления результата при его отображении пользователю. -
bounds(возвращается опционально) хранит ограничивающий прямоугольник, который может полностью содержать возвращаемый результат. Обратите внимание, что эти границы могут не соответствовать рекомендуемому окну просмотра. (Например, Сан-Франциско включает острова Фараллон , которые технически являются частью города, но, вероятно, не должны возвращаться в окне просмотра.)
-
-
plus_code(см. Открытый код местоположения и plus-коды ) — это закодированная ссылка на местоположение, полученная из координат широты и долготы, которая представляет собой область: 1/8000 градуса на 1/8000 градуса (примерно 14 м x 14 м на экваторе) или меньше. Plus-коды могут использоваться в качестве замены уличных адресов в местах, где адреса отсутствуют (где здания не пронумерованы или улицы не названы). API не всегда возвращает plus-коды.Когда служба возвращает плюс-код, он форматируется как глобальный код и составной код:
-
global_code— это 4-значный код города и 6-значный или более длинный местный код (849VCWC8+R9). -
compound_code— это локальный код длиной 6 символов или длиннее с явным местоположением (CWC8+R9, Mountain View, CA, USA). Не анализируйте это содержимое программно.
-
partial_matchуказывает, что геокодер не вернул точное совпадение для исходного запроса, хотя он смог сопоставить часть запрошенного адреса. Вы можете проверить исходный запрос на наличие опечаток и/или неполного адреса.Частичные совпадения чаще всего возникают для уличных адресов, которые не существуют в населенном пункте, который вы передаете в запросе. Частичные совпадения также могут быть возвращены, когда запрос соответствует двум или более местоположениям в одном и том же населенном пункте. Например, "Hillpar St, Bristol, UK" вернет частичное совпадение как для Henry Street, так и для Henrietta Street. Обратите внимание, что если запрос включает неправильно написанный компонент адреса, служба геокодирования может предложить альтернативный адрес. Предложения, инициированные таким образом, также будут отмечены как частичное совпадение.
-
place_id— это уникальный идентификатор, который можно использовать с другими API Google. Например, вы можете использоватьplace_idв запросе API Places , чтобы получить сведения о местном бизнесе, такие как номер телефона, часы работы, отзывы пользователей и многое другое. См. обзор идентификаторов мест .
Типы адресов и типы компонентов адреса
Массив types в ответе указывает тип адреса . Примеры типов адресов включают почтовый адрес, страну или политическую единицу. Массив types в поле address_component указывает тип каждой части адреса. Примеры включают номер дома или страну.
Адреса могут иметь несколько типов. Типы могут считаться «тегами». Например, многие города помечены 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 во Франции).
Помимо вышеперечисленного, компоненты адреса могут включать типы, перечисленные ниже.
| Тип компонента адреса | Описание |
|---|---|
floor | Адрес этажа здания. |
establishment | Обычно это место, которое еще не было категоризировано. |
landmark | Близлежащее место, которое используется в качестве ориентира для облегчения навигации. |
point_of_interest | Именованная точка интереса. |
parking | Парковка или парковочное сооружение. |
post_box | Определенный почтовый ящик. |
postal_town | Группа географических областей, таких как locality и sublocality , используемая для почтовых адресов в некоторых странах. |
room | Адрес комнаты в здании. |
street_number | Точный номер дома. |
bus_station , train_station и transit_station | Местоположение остановки автобуса, поезда или общественного транспорта. |
Смещение области просмотра
В запросе Geocoding вы можете указать службе Geocoding отдавать предпочтение результатам в пределах заданного окна просмотра (выраженного в виде ограничивающего прямоугольника). Вы делаете это в URL запроса, устанавливая параметр bounds .
Параметр bounds определяет координаты широты/долготы юго-западного и северо-восточного углов этой ограничивающей рамки, используя символ вертикальной черты ( | ) для разделения координат.
Например, геокод для «Вашингтона» обычно возвращает американский штат Вашингтон:
Запрос:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Ответ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Однако добавление аргумента bounds , определяющего ограничивающую рамку вокруг северо-восточной части США, приводит к тому, что этот геокод возвращает город Вашингтон, округ Колумбия:
Запрос:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Ответ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Региональное смещение
В запросе Geocoding вы можете указать службе Geocoding возвращать результаты, смещенные в сторону определенного региона, используя параметр region . Этот параметр принимает аргумент ccTLD (домен верхнего уровня кода страны), указывающий смещение региона. Большинство кодов ccTLD идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, ccTLD Соединенного Королевства — «uk» ( .co.uk ), а его код ISO 3166-1 — «gb» (технически для субъекта «Соединенное Королевство Великобритании и Северной Ирландии»).
Результаты геокодирования могут быть смещены для каждого домена, в котором официально запущено основное приложение Google Maps. Обратите внимание, что смещение отдает предпочтение только результатам для определенного домена; если за пределами этого домена существуют более релевантные результаты, они могут быть включены.
Например, геокод для «Толедо» возвращает этот результат, поскольку домен по умолчанию для API геокодирования установлен на Соединенные Штаты. Запрос:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Ответ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Запрос геокодирования для «Толедо» с region=es (Испания) вернет испанский город.
Запрос:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Ответ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Фильтрация компонентов
В ответе Geocoding API Geocoding может возвращать результаты адресов, ограниченные определенной областью. Вы можете указать ограничение с помощью фильтра components . Фильтр состоит из списка пар component:value , разделенных вертикальной чертой ( | ). Значения фильтра поддерживают те же методы исправления орфографии и частичного соответствия, что и другие запросы Geocoding. Если геокодер находит частичное совпадение для фильтра компонентов, ответ будет содержать поле partial_match .
components , которые можно фильтровать, включают в себя:
-
postal_codeсоответствуетpostal_codeиpostal_code_prefix. -
countryсоответствует названию страны или двухбуквенному коду страны ISO 3166-1 . API следует стандарту ISO для определения стран, и фильтрация работает лучше всего при использовании соответствующего кода ISO страны.
Следующие components могут быть использованы для влияния на результаты, но не будут применяться принудительно:
-
routeсоответствует длинному или короткому названию маршрута. -
localityсоответствует типамlocalityиsublocality. -
administrative_areaсоответствует всем уровнямadministrative_area.
Примечания о фильтрации компонентов:
- Не повторяйте эти фильтры компонентов в запросах, иначе API вернет
Invalid_request:country,postal_code,route - Если запрос содержит повторяющиеся фильтры компонентов, API оценивает эти фильтры как И, а не ИЛИ.
- Результаты соответствуют Google Maps, которые иногда выдают неожиданные ответы
ZERO_RESULTS. Использование Place Autocomplete может дать лучшие результаты в некоторых случаях использования. Чтобы узнать больше, см. этот FAQ . - Для каждого компонента адреса укажите его либо в параметре
address, либо в фильтреcomponents, но не оба. Указание одинаковых значений в обоих может привести кZERO_RESULTS.
Геокод для «High St, Hastings» с components=country:GB возвращает результат в Гастингсе, Англия, а не в Гастингсе-на-Гудзоне, США.
Запрос:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Ответ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Запрос геокодирования для населенного пункта «Санта-Крус» с components=country:ES возвращает Санта-Крус-де-Тенерифе на Канарских островах, Испания.
Запрос:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Ответ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Фильтрация компонентов возвращает ответ ZERO_RESULTS только в том случае, если вы предоставляете фильтры, которые исключают друг друга.
Запрос:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Ответ:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Вы можете делать допустимые запросы без параметра адреса, используя фильтр components . (При геокодировании полного адреса параметр address обязателен, если запрос содержит названия и номера зданий.)
Запрос:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Ответ:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}