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

Запрос

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

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

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

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

HTTPS требуется для запросов, использующих ключ API.

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

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

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

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

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

    --ИЛИ--
    components — фильтр компонентов с элементами, разделенными вертикальной чертой ( | ). Фильтр компонентов также принимается как необязательный параметр, если указан address . Каждый элемент в фильтре компонентов состоит из пары component:value и полностью ограничивает результаты геокодера. Дополнительную информацию о фильтрации компонентов см. ниже.
  • key — API-ключ вашего приложения. Этот ключ идентифицирует ваше приложение для целей управления квотами. Узнайте, как получить ключ .

Дополнительные указания см. в разделе часто задаваемых вопросов .

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

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

Ответы

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

В этом примере API геокодирования запрашивает ответ json на запрос по идентификатору места "ChIJeRpOeF67j4AR9ydy_PIzPuM". Идентификатор этого места соответствует зданию по адресу: 1600 Amphitheatre Parkway, Mountain View, CA.

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

Полученные результаты

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

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

  • Массив types[] указывает тип возвращаемого результата. Этот массив содержит набор из нуля или более тегов, определяющих тип функции, возвращаемой в результате. Например, геокод «Чикаго» возвращает «населенный пункт», который указывает, что «Чикаго» — это город, а также возвращает «политический», который указывает, что это политическая единица. Компоненты могут иметь пустой массив типов, когда для этого компонента адреса нет известных типов. API может добавлять значения нового типа по мере необходимости. Дополнительные сведения см. в разделе Типы адресов и компоненты адресов .
  • formatted_address — это строка, содержащая удобочитаемый адрес этого местоположения.

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

    Отформатированный адрес логически состоит из одного или нескольких компонентов адреса . Например, адрес «111 8th Avenue, New York, NY» состоит из следующих компонентов: «111» (номер улицы), «8th Avenue» (маршрут), «New York» (город) и «NY "(штат США).

    Не анализируйте отформатированный адрес программно. Вместо этого следует использовать отдельные компоненты адреса, которые включаются в ответ API в дополнение к форматированному полю адреса.

  • address_components[] — это массив, содержащий отдельные компоненты, применимые к данному адресу.

    Каждый компонент адреса обычно содержит следующие поля:

    • types[] — это массив, указывающий тип компонента адреса. См. список поддерживаемых типов .
    • long_name — это полное текстовое описание или имя компонента адреса, возвращаемое геокодером.
    • short_name — это сокращенное текстовое имя компонента адреса, если оно доступно. Например, компонент адреса для штата Аляска может иметь long_name «Аляска» и short_name «АК» с использованием двухбуквенной почтовой аббревиатуры.

    Обратите внимание на следующие факты о массиве address_components[] :

    • Массив компонентов адреса может содержать больше компонентов, чем formatted_address .
    • Массив не обязательно включает все политические объекты, содержащие адрес, за исключением включенных в formatted_address . Чтобы получить все политические объекты, содержащие определенный адрес, следует использовать обратное геокодирование, передавая широту/долготу адреса в качестве параметра запроса.
    • Не гарантируется, что формат ответа останется неизменным между запросами. В частности, количество address_components зависит от запрошенного адреса и может меняться со временем для одного и того же адреса. Компонент может менять позицию в массиве. Тип компонента может меняться. Определенный компонент может отсутствовать в более позднем ответе.

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

  • postcode_localities[] — это массив, обозначающий все населенные пункты, содержащиеся в почтовом индексе. Это присутствует только тогда, когда результатом является почтовый индекс, содержащий несколько населенных пунктов.
  • geometry содержит следующую информацию:
    • location содержит геокодированные значения широты и долготы. Для обычного поиска адресов это поле обычно является наиболее важным.

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

      • "ROOFTOP" означает, что возвращенный результат является точным геокодом, для которого у нас есть информация о местоположении с точностью до адреса улицы.
      • "RANGE_INTERPOLATED" указывает, что возвращенный результат отражает приближение (обычно на дороге), интерполированное между двумя точными точками (например, перекрестками). Интерполированные результаты обычно возвращаются, когда геокоды крыши недоступны для адреса улицы.
      • "GEOMETRIC_CENTER" указывает, что возвращенный результат является геометрическим центром результата, такого как ломаная линия (например, улица) или многоугольник (область).
      • "APPROXIMATE" указывает, что возвращаемый результат является приблизительным.
    • viewport содержит рекомендуемое окно просмотра для отображения возвращенного результата, заданное как два значения широты, долготы, определяющие southwest и northeast угол ограничивающего прямоугольника окна просмотра. Обычно окно просмотра используется для кадрирования результата при его отображении пользователю.
    • bounds (опционально возвращаемый) хранит ограничивающую рамку, которая может полностью содержать возвращаемый результат. Обратите внимание, что эти границы могут не совпадать с рекомендуемым окном просмотра. (Например, Сан-Франциско включает острова Фараллон , которые технически являются частью города, но, вероятно, не должны возвращаться в область просмотра.)
  • plus_code (см. Открытый код местоположения и плюсовые коды ) — это закодированная ссылка на местоположение, полученная из координат широты и долготы, которая представляет площадь: 1/8000 градуса на 1/8000 градуса (около 14 м x 14 м на экваторе) или меньше. Плюс-коды можно использовать в качестве замены уличных адресов в местах, где адреса не существуют (где здания не пронумерованы или улицы не названы). 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 указывает гражданскую единицу первого порядка ниже уровня страны. В Соединенных Штатах такими административными уровнями являются штаты. Не все страны имеют эти административные уровни. В большинстве случаев короткие имена admin_area_level_1 будут точно соответствовать подразделениям ISO 3166-2 и другим широко распространенным спискам; однако это не гарантируется, поскольку наши результаты геокодирования основаны на различных сигналах и данных о местоположении.
  • administrative_area_level_2 указывает на гражданскую единицу второго порядка ниже уровня страны. В Соединенных Штатах такими административными уровнями являются округа. Не все страны имеют эти административные уровни.
  • administrative_area_level_3 указывает гражданскую единицу третьего порядка ниже уровня страны. Этот тип указывает на второстепенную административную единицу. Не все страны имеют эти административные уровни.
  • administrative_area_level_4 указывает гражданскую единицу четвертого порядка ниже уровня страны. Этот тип указывает на второстепенную административную единицу. Не все страны имеют эти административные уровни.
  • administrative_area_level_5 указывает на гражданскую единицу пятого порядка ниже уровня страны. Этот тип указывает на второстепенную административную единицу. Не все страны имеют эти административные уровни.
  • administrative_area_level_6 указывает на гражданскую единицу шестого порядка ниже уровня страны. Этот тип указывает на второстепенную административную единицу. Не все страны имеют эти административные уровни.
  • administrative_area_level_7 указывает на гражданскую единицу седьмого порядка ниже уровня страны. Этот тип указывает на второстепенную административную единицу. Не все страны имеют эти административные уровни.
  • colloquial_area указывает обычно используемое альтернативное имя для сущности.
  • locality указывает на объединенный город или городскую политическую единицу.
  • sublocality указывает на гражданское образование первого порядка ниже населенного пункта. Для некоторых местоположений может быть получен один из дополнительных типов: sublocality_level_1 до sublocality_level_5 . Каждый уровень населенного пункта является гражданским образованием. Большие числа указывают на меньшую географическую область.
  • neighborhood указывает на именованный район
  • premise указывает на именованное место, обычно здание или группу зданий с общим названием
  • subpremise указывает на объект первого порядка под именованным местоположением, обычно отдельное здание в наборе зданий с общим названием
  • plus_code указывает закодированную ссылку на местоположение, полученную из широты и долготы. Плюс-коды можно использовать в качестве замены уличных адресов в местах, где их нет (где здания не пронумерованы или улицы не названы). Подробнее см. https://plus.codes .
  • postal_code указывает почтовый индекс, используемый для адресации почты внутри страны.
  • natural_feature указывает на заметную природную особенность.
  • airport указывает на аэропорт.
  • park указывает на названный парк.
  • point_of_interest указывает именованную достопримечательность. Как правило, эти «POI» представляют собой известные местные объекты, которые нелегко вписать в другую категорию, например «Эмпайр-стейт-билдинг» или «Эйфелева башня».

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

В дополнение к вышеперечисленному, компоненты адреса могут включать перечисленные здесь типы. Этот список не является исчерпывающим и может быть изменен.

  • floor указывает этаж здания с адресом.
  • establishment обычно указывает на место, которое еще не было классифицировано.
  • landmark указывает на близлежащее место, которое используется в качестве ориентира для облегчения навигации.
  • point_of_interest указывает именованную достопримечательность.
  • parking указывает на стоянку или стоянку.
  • post_box указывает на конкретный почтовый ящик.
  • postal_town указывает на группу географических областей, таких как locality и sublocality , которые используются для почтовых адресов в некоторых странах.
  • room указывает на номер здания с адресом.
  • street_number указывает точный номер улицы.
  • bus_station , train_station и transit_station указывают местоположение автобуса, поезда или остановки общественного транспорта.

Смещение области просмотра

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

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

Например, геокод для «Вашингтон» обычно возвращает штат Вашингтон в США:

Запрос:

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

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            },
            "location" : {
               "lat" : 47.7510741,
               "lng" : -120.7401385
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 49.0024442,
                  "lng" : -116.91558
               },
               "southwest" : {
                  "lat" : 45.543541,
                  "lng" : -124.8489739
               }
            }
         },
         "place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

Однако добавление аргумента bounds , определяющего ограничивающую рамку вокруг северо-восточной части США, приводит к тому, что этот геокод возвращает город Вашингтон, округ Колумбия:

Запрос:

https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Washington",
               "short_name" : "Washington",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "District of Columbia",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "District of Columbia",
               "short_name" : "DC",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Washington, DC, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            },
            "location" : {
               "lat" : 38.9071923,
               "lng" : -77.03687069999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 38.9958641,
                  "lng" : -76.90939299999999
               },
               "southwest" : {
                  "lat" : 38.7916449,
                  "lng" : -77.119759
               }
            }
         },
         "place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Смещение региона

В запросе геокодирования вы можете указать службе геокодирования возвращать результаты, смещенные в сторону определенного региона, используя параметр region . Этот параметр принимает аргумент ccTLD (домен верхнего уровня с кодом страны), определяющий смещение региона. Большинство кодов ccTLD идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, ccTLD Соединенного Королевства — «uk» ( .co.uk ), а его код ISO 3166-1 — «gb» (технически для субъекта «Соединенное Королевство Великобритании и Северной Ирландии»).

Результаты геокодирования могут быть необъективными для каждого домена, в котором официально запущено основное приложение Google 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 оценивает эти фильтры как И, а не как ИЛИ.
  • Результаты согласуются с Google Maps, которые иногда дают неожиданные ответы ZERO_RESULTS . В некоторых случаях использование автозаполнения мест может дать лучшие результаты. Чтобы узнать больше, см. этот FAQ .
  • Для каждого компонента адреса укажите его либо в параметре address , либо в фильтре components , но не в обоих одновременно. Указание одинаковых значений в обоих случаях может привести к ZERO_RESULTS .

Геокод для "High St, Hastings" с components=country:GB возвращает результат в Гастингсе, Англия, а не в Гастингсе-на-Гудзоне, США.

Запрос:

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

Ответ:

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

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

Запрос:

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

Ответ:

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

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

Запрос:

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

Ответ:

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

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

Запрос:

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

Ответ:

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