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

Запрос

Запрос к API геокодирования имеет следующий вид:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

где outputFormat может принимать одно из следующих значений:

• json (рекомендуется) указывает на вывод в формате JSON (JavaScript Object Notation); или
• xml указывает на вывод в формате XML

Требуется HTTPS.

Некоторые параметры являются обязательными, а некоторые — необязательными. Как это принято в URL-адресах, параметры разделяются символом амперсанда ( & ).

Остальная часть этой страницы посвящена описанию геокодирования и обратного геокодирования отдельно, поскольку для каждого типа запроса доступны разные параметры.

Параметры геокодирования (поиск по широте/долготе)

Обязательные параметры в запросе на геокодирование:

• key — API-ключ вашего приложения. Этот ключ идентифицирует ваше приложение для целей управления квотами. Узнайте, как получить ключ .

• В запросе необходимо указать либо address , либо components , либо и то, и другое:

  • address — это адрес улицы или код города , который вы хотите геокодировать. Примечание: геокодирование адресов не обрабатывает координаты широты и долготы, а также другие неструктурированные строки, не представляющие собой адрес или код города. Запросы, использующие такие строки, не поддерживаются и могут привести к ошибкам или неопределенному поведению. Примеры неподдерживаемых запросов включают следующее:

    тип запроса	Пример
    Координаты широты и долготы. Вместо этого используйте обратное геокодирование .	"37.422131,-122.084801"
    Слишком много понятий или ограничений, например, названия нескольких мест, дорог или городов в одном запросе.	«Маркет-стрит, аэропорт Сан-Франциско Сан-Хосе»
    Элементы почтового адреса, не отображаемые на Google Maps.	«Адрес: Джон Смит, Мейн-стрит, 123» "Адрес: 13, Сан-Франциско"
    Названия предприятий, сетей или категорий в сочетании с указанием мест, где эти организации недоступны.	«Магазин Tesco недалеко от Далласа, штат Техас»
    Неоднозначные запросы с множественными интерпретациями	"Сдача зарядного устройства"
    Исторические названия больше не используются.	«Мидлсекс, Соединенное Королевство»
    Негеопространственные элементы или намерения	«Сколько лодок находится в гавани Вентуры?»
    Неофициальные или самозваные названия	«Дженга» "Хелтер Скелтер"

    Адреса следует указывать в соответствии с форматом, используемым национальной почтовой службой соответствующей страны. Дополнительные элементы адреса, такие как название компании и номера помещений, офисов или этажей, следует избегать. Элементы уличного адреса следует разделять пробелами (здесь показано как url-escaped to %20 ):

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

    Форматируйте коды плюса, как показано здесь (знаки плюса экранируются как %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.

В этом примере 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.

{
    "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 , в объекте ответа геокодирования может присутствовать дополнительное поле error_message . Это поле содержит более подробную информацию о причинах присвоения данного кода состояния.

Результаты

Когда геокодер возвращает результаты, он помещает их в массив results (JSON). Даже если геокодер не возвращает результатов (например, если адрес не существует), он все равно возвращает пустой массив results . (XML-ответы состоят из нуля или более элементов <result> ).

Типичный результат содержит следующие поля:

• Массив types[] указывает тип возвращаемого результата. Этот массив содержит набор из нуля или более тегов, определяющих тип объекта, возвращаемого в результате. Например, геокод "Чикаго" возвращает "местность", что указывает на то, что "Чикаго" — это город, а также возвращает "политический", что указывает на то, что это политическое образование. Компоненты могут иметь пустой массив 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 codes ) — это закодированный идентификатор местоположения, полученный из координат широты и долготы, представляющий собой область размером 1/8000 градуса на 1/8000 градуса (примерно 14 м x 14 м на экваторе) или меньше. Plus-коды могут использоваться в качестве замены адресов улиц в местах, где адреса отсутствуют (где здания не нумеруются или улицы не имеют названий). API не всегда возвращает plus-коды.

  Когда сервис возвращает код «плюс», он форматируется как глобальный код и составной код:

  • global_code — это 4-символьный код города и 6-символьный или более длинный местный код (849VCWC8+R9).
  • compound_code — это локальный код длиной 6 символов или более, содержащий явное указание местоположения (CWC8+R9, Маунтин-Вью, Калифорния, США). Не следует программно анализировать это содержимое.
  Там, где это возможно, API возвращает как глобальный, так и составной код. Однако, если результат находится в удаленном месте (например, в океане или пустыне), может быть возвращен только глобальный код.

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

  Частичные совпадения чаще всего встречаются для адресов улиц, которых нет в указанном вами населенном пункте. Частичные совпадения также могут быть получены, когда запрос соответствует двум или более местоположениям в одном и том же населенном пункте. Например, запрос "Hillpar St, Bristol, UK" вернет частичное совпадение как для Henry Street, так и для Henrietta Street. Обратите внимание, что если запрос содержит орфографическую ошибку в адресе, служба геокодирования может предложить альтернативный адрес. Предложения, срабатывающие таким образом, также будут помечены как частичное совпадение.

• 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 Maps. Обратите внимание, что предвзятость проявляется только в результатах, отданных за пределами конкретного домена; если за пределами этого домена существуют более релевантные результаты, они могут быть включены в анализ.

Например, запрос на геокодирование для "Толедо" возвращает такой результат, поскольку домен по умолчанию для API геокодирования установлен на Соединенные Штаты. Запрос:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.454229
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Запрос геокодирования для "Толедо" с region=es (Испания) вернет испанский город.

Запрос:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&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"
}

Фильтрация компонентов

В ответе на запрос геокодирования 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 обрабатывает эти фильтры как оператор И (AND), а не ИЛИ (OR).
• Результаты соответствуют Google Maps, который иногда выдает неожиданные ответы 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"
}