Запрос
Запрос Geocoding 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 они экранируются какТип запроса Пример Координаты широты и долготы. Используйте обратное геокодирование. "37.422131,-122.084801" Слишком много понятий или ограничений, например названия нескольких мест, дорог или городов в одном запросе. "Маркет-стрит Сан-Франциско аэропорт Сан-Хосе" Элементы почтового адреса, не представленные на Google Картах "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"Названия компаний, сетей или категорий в сочетании с местоположениями, где эти объекты недоступны. "Tesco рядом с Далласом, Техас" Неоднозначные запросы, которые можно интерпретировать по-разному. "Charger drop-off" Исторические названия, которые больше не используются. "Middlesex United Kingdom" Негеопространственные элементы или намерения "Сколько лодок в гавани Вентура?" Неофициальные или рекламные названия. "Дженга"
"Хелтер Скелтер"%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– ограничивающая рамка области просмотра, внутри которой следует отдавать явное предпочтение результатам геокодирования. Этот параметр влияет на результаты работы геокодера, но не ограничивает их полностью. Подробнее…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.
В этом примере Geocoding API запрашивает ответ в формате json для адреса "1600 Amphitheatre Parkway, Mountain View, CA".
В этом запросе используется флаг JSON output:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
В этом запросе используется XML-флаг output:
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 они просто отсутствуют. Например, если результатов нет, в ответе JSON будет пустой массив
results, а в ответе XML не будет элементов<result>.
Коды статуса
Поле "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[]указывает тип возвращенного результата. Этот массив содержит набор из одного или нескольких тегов, которые определяют тип возвращаемого элемента. Например, геокодирование по запросу "Самара" возвращает тег locality, указывающий, что Самара является городом, а также тег political, указывающий, что этот объект является также административной единицей. Подробнее о типах адресов и их компонентов… formatted_address– это строка, содержащая человекочитаемый адрес этого места.Часто это почтовый адрес. В некоторых странах, таких как Великобритания, не разрешено распространение настоящих почтовых адресов в связи с ограничениями лицензирования.
Отформатированный адрес состоит из одного или нескольких компонентов адреса. Например, адрес "111 8th Avenue, New York, NY" содержит отдельные компоненты "111" (номер дома), "8th Avenue" (улица), "New York" (город) и "NY" (штат США).
Не анализируйте отформатированный адрес программно. Вместо этого используйте отдельные компоненты адреса, которые ответ API включает в дополнение к полю отформатированного адреса.
address_components[]– массив, содержащий отдельные компоненты адреса.Каждый из компонентов адреса обычно содержит следующие поля:
types[]– массив, указывающий тип компонента адреса. Если для компонента адреса нет известных типов, массив типов может быть пустым. При необходимости в API могут быть добавлены новые значения типов. Подробнее о типах адресов и их компонентов…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 Code) – это закодированная ссылка на местоположение на основе координат широты и долготы, которая представляет область: 1/8000 градуса на 1/8000 градуса (приблизительно 14 x 14 метров на экваторе) или меньше. Коды Plus Code можно использовать в качестве замены почтовым адресам там, где эти адреса не существуют (здания не пронумерованы или улицам не присвоены названия). API не всегда возвращает плюскоды.Если сервис возвращает код Plus Code, он форматируется как глобальный и составной код:
global_codeсодержит четыре знака кода региона и не менее шести знаков местного кода (849VCWC8+R9).compound_codeсодержит не менее шести знаков местного кода с данными о местоположении (CWC8+R9 для Маунтин-Вью, Калифорния, США). Не анализируйте этот контент программно.
-
partial_match– указывает, что геокодер не вернул точное совпадение для исходного запроса, хотя и обнаружил частичное совпадение с запрашиваемым адресом. Рекомендуется проверить исходный запрос на наличие в нем опечаток и/или неполного адреса.В большинстве случаев частичные совпадения возникают при использовании почтовых адресов, которые отсутствуют в местности, указанной в запросе. Частичные совпадения могут также возвращаться для запросов, в которых имеется соответствие нескольким местоположениям в пределах одной местности. Например, запрос "Воронеж, улица Лиз" вернет частично совпадающие результаты "улица Лизюкова" и "улица Лизы Чайкиной". Обратите внимание: если запрос содержит ошибки в написании адреса, сервис геокодирования может предложить альтернативный адрес. Такие предложения также будут помечены как частичные совпадения.
place_id– уникальный идентификатор, который можно использовать и с другими API Google. Например, вы можете использоватьplace_idв запросе Places API для получения подробной информации о местной организации (номер телефона, часы работы, отзывы клиентов и т. д.). Подробнее об идентификаторе места…
Типы адресов и их компонентов
Массив 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 |
Код местоположения на основе широты и долготы. Коды 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 |
Местоположение остановки автобуса, поезда или другого общественного транспорта. |
Предпочтение области просмотра
В запросе на геокодирование можно указать, чтобы сервис геокодирования в первую очередь выводил результаты в указанной области просмотра (выраженной граничной рамкой). Для этого в 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"
}
Привязка к региону
В запросе геокодирования можно указать, чтобы сервис геокодирования в первую очередь выводил результаты в определенном регионе. Для этого служит параметр region. Этот параметр принимает аргумент ccTLD (национальный домен верхнего уровня), указывающий на приоритет региона. Большинство кодов ccTLD совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически относится к Соединенному Королевству Великобритании и Северной Ирландии).
Результаты геокодирования можно смещать для любого домена, в котором официально запущено главное приложение Google Карт. Следует отметить, что этот параметр указывает только на предпочтение результатов, найденных в рамках определенных границ. Если за пределами этих границ обнаруживаются более релевантные результаты, они могут быть включены в результат.
Например, поскольку США являются доменом по умолчанию для Geocoding 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 может возвращать адреса, ограниченные определенной областью. Ограничение можно задать с помощью фильтра components. Фильтр состоит из списка пар component:value, разделенных вертикальной чертой (|). Значения фильтра поддерживают те же методы проверки орфографии и частичного соответствия, что и другие запросы геокодирования. Если геокодер находит частичное совпадение для фильтра компонентов, ответ будет содержать поле 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"
}
Вы можете создавать действительные запросы без параметра address, используя фильтр 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"
}