Запрос и ответ геокодирования

Запрос

Запрос 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 – почтовый адрес или плюс-код, для которого нужно выполнить геокодирование. Примечание. Геокодирование адресов не работает с координатами широты и долготы, а также с другими неструктурированными строками, которые не представляют собой адрес или плюс-код. Запросы с такими строками не поддерживаются и могут привести к ошибкам или неопределенному поведению. Примеры неподдерживаемых запросов:

    Тип запроса	Пример
    Координаты широты и долготы. Используйте обратное геокодирование.	"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"
    Негеопространственные элементы или намерения	"Сколько лодок в гавани Вентура?"
    Неофициальные или рекламные названия.	"Дженга" "Хелтер Скелтер"

    Указывайте адреса в формате, принятом для почтовых адресов в нужной вам стране. Не указывайте дополнительные данные, например названия компаний, номера этажей и квартир. Элементы почтового адреса должны быть разделены пробелами (в URL они экранируются как %20):

    address=24%20Sussex%20Drive%20Ottawa%20ON

    Коды Plus Code следует форматировать так, как в примере ниже (символы плюса экранируются в URL как %2B, а пробелы – как %20):
    • Глобальный код содержит 4 знака кода региона и 6 и более знаков местного кода (849VCWC8+R9 – это 849VCWC8%2BR9).
    • Составной код содержит 6 и более знаков местного кода с точными данными о местоположении (CWC8+R9 для Маунтин-Вью, Калифорния, США, имеет значение CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • 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 – подробнее о том, как добавить входы и контуры зданий.
  Чтобы включить несколько функций для одного запроса к API, добавьте в него параметр 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, выберите нужную вкладку ниже.

{
    "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"
}

<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>

Коды статуса

Поле "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 для Маунтин-Вью, Калифорния, США). Не анализируйте этот контент программно.
  Если возможно, API возвращает и глобальный, и составной код. Однако если результат находится в отдаленном месте, например в океане или пустыне, может быть возвращен только глобальный код.

• partial_match – указывает, что геокодер не вернул точное совпадение для исходного запроса, хотя и обнаружил частичное совпадение с запрашиваемым адресом. Рекомендуется проверить исходный запрос на наличие в нем опечаток и/или неполного адреса.

  В большинстве случаев частичные совпадения возникают при использовании почтовых адресов, которые отсутствуют в местности, указанной в запросе. Частичные совпадения могут также возвращаться для запросов, в которых имеется соответствие нескольким местоположениям в пределах одной местности. Например, запрос "Воронеж, улица Лиз" вернет частично совпадающие результаты "улица Лизюкова" и "улица Лизы Чайкиной". Обратите внимание: если запрос содержит ошибки в написании адреса, сервис геокодирования может предложить альтернативный адрес. Такие предложения также будут помечены как частичные совпадения.

• place_id – уникальный идентификатор, который можно использовать и с другими API Google. Например, вы можете использовать place_id в запросе Places API для получения подробной информации о местной организации (номер телефона, часы работы, отзывы клиентов и т. д.). Подробнее об идентификаторе места…

Типы адресов и их компонентов

Массив types в ответе указывает тип адреса. Примеры типов адресов: почтовый адрес, страна или административная единица. Массив types в поле address_component указывает тип каждой части адреса. Примеры включают в себя номер дома или название страны.

Адреса могут иметь несколько типов. Эти типы можно считать тегами. Например, для многих городов используются теги типов political и locality.

В массивах типов адреса и типов компонентов адреса поддерживаются и возвращаются следующие типы:

Пустой список типов указывает, что для того или иного элемента адреса нет известных типов, например lieu-dit во Франции.

Помимо вышеперечисленных, компоненты адреса могут иметь типы, указанные ниже.

Предпочтение области просмотра

В запросе на геокодирование можно указать, чтобы сервис геокодирования в первую очередь выводил результаты в указанной области просмотра (выраженной граничной рамкой). Для этого в 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&region=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"
}