Запрос
Запрос 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 Mountain View, CA, USA — это
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- глобальный код — это 4-значный код города и 6-значный или более длинный локальный код (849VCWC8+R9 =
-
components— фильтр компонентов, элементы которого разделены вертикальной чертой (|). Фильтр компонентов также принимается в качестве необязательного параметра, если указанaddress. Каждый элемент фильтра компонентов состоит из парыcomponent:valueи полностью ограничивает результаты геокодера. Подробнее о фильтрации компонентов см. ниже.
-
Дополнительные рекомендации см. в разделе часто задаваемых вопросов .
Необязательные параметры в запросе геокодирования:
-
bounds— ограничивающая рамка области просмотра, в пределах которой результаты геокодирования будут смещены более заметно. Этот параметр влияет только на результаты геокодирования, но не ограничивает их полностью. (Подробнее см. раздел «Смещение области просмотра» ниже.) -
language— язык, на котором будут возвращаться результаты.- Ознакомьтесь со списком поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
- Если
languageне указан, геокодер попытается использовать предпочитаемый язык, указанный в заголовкеAccept-Language, или родной язык домена, с которого отправлен запрос. - Геокодер делает всё возможное, чтобы предоставить адрес, понятный как пользователю, так и местным жителям. Для этого он возвращает адреса на местном языке, при необходимости транслитерируя их в удобный для пользователя язык с учётом выбранного языка. Все остальные адреса возвращаются на выбранном языке. Все компоненты адреса возвращаются на одном языке, выбранном из первого компонента.
- Если имя отсутствует на предпочитаемом языке, геокодер использует наиболее близкое совпадение.
- Предпочтительный язык оказывает небольшое влияние на набор результатов, возвращаемых API, и порядок их возврата. Геокодер интерпретирует сокращения по-разному в зависимости от языка, например, сокращения для типов улиц или синонимы, которые могут быть корректны в одном языке, но некорректны в другом. Например, utca и tér в венгерском языке являются синонимами для street и square соответственно.
-
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-деревьев требует осторожности, поэтому необходимо ссылаться на правильные узлы и элементы. См. раздел «Анализ XML с помощью XPath», где приведены рекомендуемые шаблоны проектирования для обработки выходных данных.
- Результаты XML помещаются в корневой элемент
<GeocodeResponse>. - JSON обозначает записи с несколькими элементами с помощью массивов множественного числа (
types), тогда как XML обозначает их с помощью нескольких единичных элементов (<type>). - Пустые элементы обозначаются пустыми массивами в JSON, но отсутствием таких элементов в XML. Например, ответ, не генерирующий никаких результатов, вернёт пустой массив
resultsв JSON, но не будет элементов<result>в XML.
Коды статуса
Поле "status" в объекте ответа Geocoding содержит статус запроса и может содержать отладочную информацию, которая поможет вам определить причину сбоя геокодирования. Поле "status" может содержать следующие значения:
-
"OK"означает, что ошибок не произошло; адрес был успешно проанализирован и возвращен как минимум один геокод. -
"ZERO_RESULTS"означает, что геокодирование прошло успешно, но не вернуло результатов. Это может произойти, если геокодеру был передан несуществующийaddress. -
OVER_DAILY_LIMITуказывает на любое из следующего:- Ключ API отсутствует или недействителен.
- В вашем аккаунте не включена функция выставления счетов.
- Превышен установленный лимит использования.
- Предоставленный способ оплаты больше не действителен (например, истек срок действия кредитной карты).
Чтобы узнать, как это исправить, ознакомьтесь с разделом FAQ по Картам .
-
"OVER_QUERY_LIMIT"означает, что вы превысили свою квоту. -
"REQUEST_DENIED"означает, что ваш запрос был отклонен. -
"INVALID_REQUEST"обычно указывает на то, что запрос (address,componentsилиlatlng) отсутствует. -
"UNKNOWN_ERROR"означает, что запрос не удалось обработать из-за ошибки сервера. Запрос может быть выполнен успешно, если вы повторите попытку.
Сообщения об ошибках
Если геокодер возвращает код статуса, отличный от OK , в объекте ответа Geocoding может быть дополнительное поле error_message . Это поле содержит более подробную информацию о причинах данного кода статуса.
Результаты
Когда геокодер возвращает результаты, он помещает их в массив results (JSON). Даже если геокодер не возвращает результатов (например, если адрес не существует), он всё равно возвращает пустой массив results . (XML-ответы состоят из нуля или более элементов <result> .)
Типичный результат содержит следующие поля:
- Массив
types[]указывает тип возвращаемого результата. Этот массив содержит набор из нуля или более тегов, определяющих тип объекта, возвращаемого в результате. Например, геокодирование «Чикаго» возвращает «локальность», что означает, что «Чикаго» — это город, а также возвращает «политический», что означает, что это политическая единица. Компоненты могут иметь пустой массив типов, если для данного компонента адреса нет известных типов. 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содержит рекомендуемую область просмотра для отображения возвращаемого результата, заданную двумя значениями широты и долготы, определяющимиsouthwestиnortheastуглы ограничивающей рамки области просмотра. Обычно область просмотра используется для обрамления результата при его отображении пользователю. -
bounds(возвращаемые опционально) хранят ограничивающую рамку, которая может полностью содержать возвращаемый результат. Обратите внимание, что эти границы могут не соответствовать рекомендуемой области просмотра. (Например, Сан-Франциско включает острова Фараллон , которые технически являются частью города, но, вероятно, не должны возвращаться в области просмотра.)
-
-
plus_code(см. Open Location Code и Plus-коды ) — это закодированная ссылка на местоположение, полученная на основе координат широты и долготы, которая представляет область размером 1/8000 градуса на 1/8000 градуса (примерно 14 м x 14 м на экваторе) или меньше. Plus-коды могут использоваться для замены уличных адресов в местах, где адреса отсутствуют (где здания не пронумерованы или улицы не имеют названий). API не всегда возвращает Plus-коды.Когда служба возвращает плюс-код, он форматируется как глобальный код и составной код:
-
global_code— это 4-значный код города и 6-значный или более длинный местный код (849VCWC8+R9). -
compound_code— это локальный код длиной не менее 6 символов с явным указанием местоположения (CWC8+R9, Маунтин-Вью, Калифорния, США). Не анализируйте это содержимое программно.
-
partial_matchозначает, что геокодер не вернул точное совпадение для исходного запроса, хотя и смог сопоставить часть запрошенного адреса. Рекомендуем проверить исходный запрос на наличие опечаток и/или неполного адреса.Частичные совпадения чаще всего возникают для уличных адресов, не существующих в указанном вами населённом пункте. Частичные совпадения также могут быть возвращены, когда запрос соответствует двум или более местоположениям в одном и том же населённом пункте. Например, запрос «Hillpar St, Bristol, UK» вернёт частичное совпадение как для улицы Генри, так и для улицы Генриетта. Обратите внимание: если запрос содержит опечатку в адресе, служба геокодирования может предложить альтернативный адрес. Предложения, полученные таким образом, также будут отмечены как частичное совпадение.
-
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 – sublocality_level_5 . Каждый уровень населённого пункта является гражданской единицей. Большие числа указывают на меньшую географическую область. |
neighborhood | Район с собственным названием. |
premise | Имеющее название место, обычно здание или группа зданий с общим названием. |
subpremise | Адресуемая сущность, расположенная ниже уровня помещения, например квартира, блок или апартаменты. |
plus_code | Код местоположения, полученный из широты и долготы. Плюс-коды могут использоваться для замены уличных адресов в местах, где их нет (где здания не пронумерованы или улицы не имеют названий). Подробнее см. https://plus.codes . |
postal_code | Почтовый индекс, используемый для адресации почтовых отправлений внутри страны. |
natural_feature | Выдающаяся природная достопримечательность. |
airport | Аэропорт. |
park | Парк с названием. |
point_of_interest | Имеющаяся точка интереса. Обычно такие «точки интереса» представляют собой известные местные объекты, которые сложно отнести к другой категории, например, «Эмпайр-стейт-билдинг» или «Эйфелева башня». |
Пустой список типов указывает на то, что для конкретного компонента адреса не существует известных типов (например, 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 Карт. Обратите внимание, что смещение отдаёт предпочтение только результатам для определённого домена; если за его пределами существуют более релевантные результаты, они могут быть включены.
Например, геокодирование для «Толедо» возвращает такой результат, поскольку домен по умолчанию для 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 Карт, которые иногда возвращают неожиданные ответы
ZERO_RESULTS. Использование функции автозаполнения мест может дать лучшие результаты в некоторых случаях. Подробнее см. в разделе часто задаваемых вопросов . - Для каждого компонента адреса укажите его либо в параметре
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"
}