Эта страница переведена с помощью Cloud Translation API.

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

Запрос

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

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

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

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

Требуется HTTPS.

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

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

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

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

address — адрес или плюсовый код , который вы хотите геокодировать. Укажите адреса в соответствии с форматом, используемым национальной почтовой службой соответствующей страны. Следует избегать дополнительных элементов адреса, таких как названия компаний и номера подразделений, помещений или этажей. Элементы почтового адреса должны быть разделены пробелами (здесь они экранированы как URL-адрес %20 ):
```
address=24%20Sussex%20Drive%20Ottawa%20ON
```
Формат плюс коды, как показано здесь (знаки плюс экранируются как URL-адрес %2B , а пробелы экранируются как %20 ):
- глобальный код — это 4-значный код региона и 6-значный или более местный код (849VCWC8+R9 — это 849VCWC8%2BR9 ).
- Составной код — это локальный код длиной 6 или более символов с явным местоположением (CWC8+R9 Маунтин-Вью, Калифорния, США — CWC8%2BR9%20Mountain%20View%20CA%20USA ).
--ИЛИ--
components — Фильтр компонентов с элементами, разделенными вертикальной чертой ( | ). Фильтр компонентов также принимается как необязательный параметр, если указан address . Каждый элемент в фильтре компонентов состоит из пары component:value и полностью ограничивает результаты геокодера. Дополнительную информацию о фильтрации компонентов см. ниже.
key — ключ API вашего приложения. Этот ключ идентифицирует ваше приложение для целей управления квотами. Узнайте, как получить ключ .

Пожалуйста, обратитесь к FAQ для получения дополнительных инструкций.

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

bounds — ограничивающая рамка области просмотра, в пределах которой можно более заметно смещать результаты геокодирования. Этот параметр будет влиять только на результаты геокодера, но не ограничивать их полностью. (Дополнительную информацию см. в разделе «Смещение видового экрана» ниже.)
language — язык, на котором возвращаются результаты.
- См. список поддерживаемых языков . Google часто обновляет поддерживаемые языки, поэтому этот список может быть неполным.
- Если language не указан, геокодер пытается использовать предпочтительный язык, указанный в заголовке Accept-Language , или родной язык домена, из которого отправлен запрос.
- Геокодер делает все возможное, чтобы предоставить адрес, который будет удобен для чтения как пользователем, так и местными жителями. Для достижения этой цели он возвращает адреса на местном языке, транслитерированные в сценарий, который при необходимости читается пользователем, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, выбранном из первого компонента.
- Если имя недоступно на предпочитаемом языке, геокодер использует наиболее близкое совпадение.
- Предпочитаемый язык оказывает небольшое влияние на набор результатов, которые API выбирает для возврата, и порядок их возврата. Геокодер интерпретирует сокращения по-разному в зависимости от языка, например сокращения типов улиц или синонимы, которые могут быть допустимы на одном языке, но недопустимы на другом. Например, utca и tér на венгерском языке являются синонимами улицы и площади соответственно.
region — код региона, указанный в виде двухсимвольного значения ccTLD («домен верхнего уровня»). Этот параметр будет влиять только на результаты геокодера, но не ограничивать их полностью. (Дополнительную информацию см. в разделе «Смещение региона» ниже.) Этот параметр также может влиять на результаты в соответствии с действующим законодательством.
components — Фильтр компонентов с элементами, разделенными вертикальной чертой ( | ). Фильтр компонентов необходим , если запрос не включает address . Каждый элемент в фильтре компонентов состоит из пары component:value и полностью ограничивает результаты геокодера. Дополнительную информацию о фильтрации компонентов см. ниже.

Ответы

Ответы на геокодирование возвращаются в формате, указанном output флагом в URL-запросе, или в формате JSON по умолчанию.

В этом примере API геокодирования запрашивает ответ json для запроса идентификатора места «ChIJeRpOeF67j4AR9ydy_PIzPuM». Этот идентификатор места относится к зданию по адресу: 1600 Amphitheatre Parkway, Маунтин-Вью, Калифорния.

Этот запрос демонстрирует использование output флага JSON:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Этот запрос демонстрирует использование флага output XML:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&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"
                    ]
                }
            ],
            "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
            "geometry": {
                "location": {
                    "lat": 37.4224428,
                    "lng": -122.0842467
                },
                "location_type": "ROOFTOP",
                "viewport": {
                    "northeast": {
                        "lat": 37.4239627802915,
                        "lng": -122.0829089197085
                    },
                    "southwest": {
                        "lat": 37.4212648197085,
                        "lng": -122.0856068802915
                    }
                }
            },
            "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
            "plus_code": {
                "compound_code": "CWC8+X8 Mountain View, CA",
                "global_code": "849VCWC8+X8"
            },
            "types": [
                "street_address"
            ]
        }
    ],
    "status": "OK"
}

Обратите внимание, что ответ JSON содержит два корневых элемента:

"status" содержит метаданные по запросу. См. коды состояния ниже.
"results" содержит массив геокодированной адресной информации и информации о геометрии.

Обычно при поиске адреса возвращается только одна запись в массиве "results" , хотя геокодер может возвращать несколько результатов, если адресные запросы неоднозначны.

XML

<GeocodeResponse>
    <status>OK</status>
    <result>
        <type>street_address</type>
        <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
        <address_component>
            <long_name>1600</long_name>
            <short_name>1600</short_name>
            <type>street_number</type>
        </address_component>
        <address_component>
            <long_name>Amphitheatre Parkway</long_name>
            <short_name>Amphitheatre Pkwy</short_name>
            <type>route</type>
        </address_component>
        <address_component>
            <long_name>Mountain View</long_name>
            <short_name>Mountain View</short_name>
            <type>locality</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>Santa Clara County</long_name>
            <short_name>Santa Clara County</short_name>
            <type>administrative_area_level_2</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>California</long_name>
            <short_name>CA</short_name>
            <type>administrative_area_level_1</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>United States</long_name>
            <short_name>US</short_name>
            <type>country</type>
            <type>political</type>
        </address_component>
        <address_component>
            <long_name>94043</long_name>
            <short_name>94043</short_name>
            <type>postal_code</type>
        </address_component>
        <geometry>
            <location>
                <lat>37.4224428</lat>
                <lng>-122.0842467</lng>
            </location>
            <location_type>ROOFTOP</location_type>
            <viewport>
                <southwest>
                    <lat>37.4212648</lat>
                    <lng>-122.0856069</lng>
                </southwest>
                <northeast>
                    <lat>37.4239628</lat>
                    <lng>-122.0829089</lng>
                </northeast>
            </viewport>
        </geometry>
        <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
        <plus_code>
            <global_code>849VCWC8+X8</global_code>
            <compound_code>CWC8+X8 Mountain View, CA</compound_code>
        </plus_code>
    </result>
</GeocodeResponse>

Обратите внимание, что ответ XML состоит из одного <GeocodeResponse> и двух элементов верхнего уровня:

<status> содержит метаданные запроса. См. коды состояния ниже.
Ноль или более элементов <result> , каждый из которых содержит один набор геокодированной информации об адресе и информации о геометрии.

Ответ XML значительно длиннее, чем ответ JSON. По этой причине мы рекомендуем использовать json в качестве предпочтительного выходного флага, если только вашей службе по какой-то причине не требуется xml . Кроме того, обработка деревьев XML требует некоторой осторожности, чтобы вы ссылались на правильные узлы и элементы. См. раздел «Разбор XML с помощью XPath», где приведены некоторые рекомендуемые шаблоны проектирования для обработки вывода.

Результаты XML заключаются в корневой элемент <GeocodeResponse> .
JSON обозначает записи с несколькими элементами с помощью массивов множественного числа ( types ), а XML обозначает их с помощью нескольких элементов в единственном числе ( <type> ).
Пустые элементы обозначаются пустыми массивами в JSON, но отсутствием таких элементов в XML. Ответ, который не генерирует результатов, вернет, например, пустой массив results в формате JSON, но не будет элементов <result> в XML.

Коды состояния

Поле "status" в объекте ответа геокодирования содержит статус запроса и может содержать отладочную информацию, которая поможет вам выяснить, почему геокодирование не работает. Поле "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[] указывает тип возвращаемого результата. Этот массив содержит набор из нуля или более тегов, определяющих тип объекта, возвращаемого в результате. Например, геокод «Чикаго» возвращает «местность», что указывает на то, что «Чикаго» — это город, а также возвращает «политический», который указывает на то, что это политическое образование. Компоненты могут иметь пустой массив типов, если для этого компонента адреса нет известных типов. При необходимости 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 «Аляска» и short_name «АК», используя двухбуквенное почтовое сокращение.
Обратите внимание на следующие факты о массиве 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 (см. Открытый код местоположения и плюсовые коды ) — это закодированная ссылка на местоположение, полученная из координат широты и долготы, которая представляет собой площадь: 1/8000 градуса на 1/8000 градуса (около 14 х 14 м на экваторе). или меньше. Коды Plus можно использовать вместо уличных адресов в местах, где адреса не существуют (где здания не пронумерованы или улицы не названы). API не всегда возвращает плюсовые коды.
Когда служба возвращает код плюса, он форматируется как глобальный код и составной код:
- global_code — это 4-значный код города и 6-значный или более местный код (849VCWC8+R9).
- compound_code — это локальный код длиной 6 или более символов с явным местоположением (CWC8+R9, Маунтин-Вью, Калифорния, США). Не анализируйте этот контент программно.
Если доступно, API возвращает как глобальный код, так и составной код. Однако если результат находится в удаленном месте (например, в океане или пустыне), может быть возвращен только глобальный код.
partial_match указывает, что геокодер не вернул точное совпадение с исходным запросом, хотя и смог сопоставить часть запрошенного адреса. Вы можете проверить исходный запрос на предмет орфографических ошибок и/или неполного адреса.
Частичные совпадения чаще всего встречаются для адресов, которые не существуют в населенном пункте, который вы передаете в запросе. Частичные совпадения также могут быть возвращены, когда запрос соответствует двум или более местоположениям в одном и том же месте. Например, «Хиллпар-стрит, Бристоль, Великобритания» вернет частичное совпадение как для Генри-стрит, так и для Генриетты-стрит. Обратите внимание: если запрос содержит компонент адреса с ошибкой, служба геокодирования может предложить альтернативный адрес. Предложения, созданные таким образом, также будут помечены как частичное совпадение.
place_id — это уникальный идентификатор, который можно использовать с другими API Google. Например, вы можете использовать place_id в запросе Places API , чтобы получить подробную информацию о местной компании, такую как номер телефона, часы работы, отзывы пользователей и многое другое. См. обзор идентификаторов мест .

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

Массив types[] в результате указывает тип адреса . Примеры типов адресов включают почтовый адрес, страну или политическое образование. В address_components[] также есть массив types[] , указывающий тип каждой части адреса. Примеры включают номер улицы или страну. (Ниже приведен полный список типов.) Адреса могут иметь несколько типов. Эти типы можно считать «тегами». Например, многие города отмечены political тегами и типом locality .

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

street_address указывает точный адрес.
route указывает именованный маршрут (например, «US 101»).
intersection указывает на крупный перекресток, обычно двух основных дорог.
political указывает на политическую сущность. Обычно этот тип обозначает полигон какой-либо гражданской администрации.
country указывает национальное политическое образование и обычно является типом высшего порядка, возвращаемым геокодером.
administrative_area_level_1 указывает гражданское лицо первого порядка ниже уровня страны. В Соединенных Штатах такими административными уровнями являются штаты. Не все страны демонстрируют эти административные уровни. В большинстве случаев короткие названия административной_области_уровня_1 будут точно соответствовать подразделениям ISO 3166-2 и другим широко распространенным спискам; однако это не гарантируется, поскольку наши результаты геокодирования основаны на различных сигналах и данных о местоположении.
administrative_area_level_2 указывает на гражданский объект второго порядка ниже уровня страны. В Соединенных Штатах такими административными уровнями являются округа. Не все страны демонстрируют эти административные уровни.
administrative_area_level_3 указывает на гражданское лицо третьего порядка ниже уровня страны. Этот тип указывает на незначительное гражданское деление. Не все страны демонстрируют эти административные уровни.
administrative_area_level_4 указывает на гражданский объект четвертого порядка ниже уровня страны. Этот тип указывает на незначительное гражданское деление. Не все страны демонстрируют эти административные уровни.
administrative_area_level_5 указывает на гражданскую единицу пятого порядка ниже уровня страны. Этот тип указывает на незначительное гражданское деление. Не все страны демонстрируют эти административные уровни.
administrative_area_level_6 указывает на гражданскую единицу шестого порядка ниже уровня страны. Этот тип указывает на незначительное гражданское деление. Не все страны демонстрируют эти административные уровни.
administrative_area_level_7 указывает на гражданское лицо седьмого порядка ниже уровня страны. Этот тип указывает на незначительное гражданское деление. Не все страны демонстрируют эти административные уровни.
colloquial_area указывает часто используемое альтернативное имя объекта.
locality указывает на объединенное политическое образование города или поселка.
sublocality указывает на гражданское образование первого порядка ниже населенного пункта. Для некоторых локаций может быть присвоен один из дополнительных типов: sublocality_level_1 до sublocality_level_5 . Каждый уровень сублокации является гражданским образованием. Большие числа указывают на меньшую географическую область.
neighborhood указывает на именованный район
premise указывает на названное место, обычно это здание или совокупность зданий с общим названием.
subpremise указывает на объект первого порядка ниже именованного местоположения, обычно это отдельное здание в группе зданий с общим названием.
plus_code указывает закодированную ссылку на местоположение, полученную на основе широты и долготы. Плюсовые коды можно использовать вместо адресов в местах, где их нет (где здания не пронумерованы или улицы не названы). Подробности см. на https://plus.codes .
postal_code указывает почтовый индекс, используемый для адреса почтовой почты внутри страны.
natural_feature указывает на выдающуюся природную особенность.
airport указывает на аэропорт.
park указывает на именованный парк.
point_of_interest указывает на именованную достопримечательность. Как правило, эти «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 указывают местоположение остановки автобуса, поезда или общественного транспорта.

Примечание. API геокодирования не гарантирует, что вернет какой-либо конкретный компонент для адреса в нашем наборе данных. То, что можно рассматривать как город, например Бруклин, может отображаться не как местность, а как другой компонент — в данном случае sublocality_level_1. Какие именно возвращаемые компоненты могут быть изменены без предварительного уведомления. Создавайте гибкий код, если вы пытаетесь извлечь компоненты адреса из ответа.

Смещение видового экрана

В запросе на геокодирование вы можете указать службе геокодирования отдавать предпочтение результатам в пределах заданной области просмотра (выраженной в виде ограничивающей рамки). Вы делаете это в URL-адресе запроса, устанавливая параметр bounds .

Параметр bounds определяет координаты широты и долготы юго-западного и северо-восточного углов этой ограничивающей рамки с помощью символа вертикальной черты ( | ) для разделения координат.

Примечание. Это только добавляет смещение к результатам в области просмотра и не гарантирует, что все или какие-либо результаты будут содержаться в нем. Конечная точка автозаполнения Places API обычно лучше подходит для неоднозначных запросов и может ограничивать результаты определенной областью. В статье с рекомендациями по геокодированию представлены некоторые рекомендации относительно того, какая конечная точка API лучше всего подходит для каждого варианта использования.

Например, геокод «Вашингтон» обычно возвращает американский штат Вашингтон:

Запрос:

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, за некоторыми заметными исключениями. Например, нДВУ Соединенного Королевства — «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 страны.
Примечание. Если вы получаете неожиданные результаты с кодом страны, убедитесь, что вы используете код, который включает страны, зависимые территории и особые области географического интереса, которые вы хотите использовать. Информацию о кодах можно найти в Википедии: Список кодов стран ISO 3166 или на платформе онлайн-просмотра ISO .

Следующие components могут использоваться для влияния на результаты, но не будут применяться принудительно:

route соответствует длинному или короткому имени маршрута.
locality соответствует типам locality и sublocality .
administrative_area соответствует всем уровням administrative_area .

Примечания о фильтрации компонентов:

Не повторяйте эти фильтры компонентов в запросах, иначе API вернет Invalid_request : country , postal_code , route
Если запрос содержит повторяющиеся фильтры компонентов, API оценивает эти фильтры как И, а не ИЛИ.
Результаты соответствуют данным Карт Google, которые иногда дают неожиданные ответы ZERO_RESULTS . Использование автозаполнения мест может дать лучшие результаты в некоторых случаях. Чтобы узнать больше, прочтите этот FAQ .
Для каждого компонента адреса укажите его либо в параметре address , либо в фильтре components , но не в обоих случаях. Указание одинаковых значений в обоих случаях может привести к результату ZERO_RESULTS .

Геокодирование для «Хай-Стрит, Гастингс» с components=country:GB возвращает результат в Гастингсе, Англия, а не в Гастингсе-на-Гудзоне, США.

Запрос:

https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "High Street",
               "short_name" : "High St",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Hastings",
               "short_name" : "Hastings",
               "types" : [ "postal_town" ]
            },
            {
               "long_name" : "East Sussex",
               "short_name" : "East Sussex",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "England",
               "short_name" : "England",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United Kingdom",
               "short_name" : "GB",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "TN34 3EY",
               "short_name" : "TN34 3EY",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "High St, Hastings TN34 3EY, UK",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            },
            "location" : {
               "lat" : 50.85830319999999,
               "lng" : 0.5924594
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 50.8601041,
                  "lng" : 0.5957329
               },
               "southwest" : {
                  "lat" : 50.8559061,
                  "lng" : 0.5906163
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Запрос геокодирования для местности «Санта-Крус» с components=country:ES возвращает Санта-Крус-де-Тенерифе на Канарских островах, Испания.

Запрос:

https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canary Islands",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Фильтрация компонентов возвращает ответ ZERO_RESULTS только если вы предоставляете фильтры, исключающие друг друга.

Запрос:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Ответ:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

Вы можете делать правильные запросы без параметра адреса, используя фильтр components . (При геокодировании полного адреса параметр address обязателен, если запрос содержит названия и номера зданий.)

Запрос:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annankatu",
               "short_name" : "Annankatu",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsinki",
               "short_name" : "HKI",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00101",
               "short_name" : "00101",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annankatu, 00101 Helsinki, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9433353
               },
               "southwest" : {
                  "lat" : 60.16226160000001,
                  "lng" : 24.9332897
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}