Google Maps Geocoding API

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

Геокодирование – процесс преобразования адресов (например, "1600 Amphitheatre Parkway, Mountain View, CA") в географические координаты (например, широта 37,423021 и долгота -122,083739), которые можно использовать для размещения маркеров на карте или ее позиционирования.

Обратное геокодирование – это процесс преобразования географических координат в адреса, понятные для пользователя. Представленная в Google Maps Geocoding API служба обратного геокодирования также позволяет найти адрес по указанному идентификатору места.

Google Maps Geocoding API обеспечивает непосредственный доступ к этим службам через запрос HTTP.

Перед началом работы

Этот документ предназначен для разработчиков веб-сайтов и мобильных приложений, которые хотят использовать в картах данные геокодирования, предоставляемые одним из интерфейсов Google Maps API.

Эта служба предполагает геокодирование статичных (заранее известных) адресов с целью размещения контента приложения на карте; она не предназначена, например, для реагирования на ввод данных в режиме реального времени. Информация о геокодировании динамических адресов (например, в рамках элемента пользовательского интерфейса) представлена в документации для Google Maps JavaScript API Client Geocoder или Google Play Services Location API.

Геокодирование требует времени и интенсивного использования ресурсов. Рекомендуется выполнить, по возможности, геокодирование известных адресов заранее (с помощью описанного здесь Google Maps Geocoding API или другой службы геокодирования) и сохранить полученные результаты во временном кэше.

Для использования Google Maps Geocoding API вам понадобится ключ API.

Получение ключа Ограничения на использование

Формат запроса Google Maps Geocoding API

Запрос Google Maps Geocoding API должен иметь следующий формат:

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

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

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

Для доступа к Google Maps Geocoding API через HTTP используйте следующий формат:

http://maps.googleapis.com/maps/api/geocode/output?parameters

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

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

В своих запросах геокодирования пользователи Google Maps API for Work должны указывать действительные параметры client и signature. Дополнительную информацию см. на странице Google Maps API for Work Web Services.

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

Геокодирование (поиск по широте и долготе)

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

• address – точный адрес, который необходимо геокодировать, в формате, используемом почтовой службой соответствующей страны. В этом параметре не следует указывать дополнительные элементы адреса, такие как наименование организации или подразделения, номер подъезда или этажа. Дополнительные указания см. в разделе Часто задаваемые вопросы.
       или
  components – фильтр компонентов, для которых необходимо выполнить геокодирование. Дополнительные сведения см. в разделе Фильтрация компонентов. Фильтр компонентов также принимается как дополнительный параметр, если указан address.
• key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. См. дополнительную информацию о получении ключа.

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

• bounds – граница области просмотра, внутри которой отдается предпочтение результатам геокодирования. Этот параметр влияет на результаты работы геокодировщика, но не ограничивает их полностью. (Дополнительную информацию можно найти в разделе Предпочтение области просмотра ниже.)
• language – язык, на котором выводятся результаты. См. список поддерживаемых языков домена. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным. Если параметр language не указан, геокодировщик будет по возможности использовать основной язык домена, из которого отправлен запрос.
• region – код региона, указываемый как значение ccTLD ("домен верхнего уровня") из двух символов. Этот параметр влияет на результаты работы геокодировщика, но не ограничивает их полностью. (Дополнительную информацию можно найти в разделе Привязка к региону ниже.)
• components – фильтры компонентов, разделяемые вертикальной чертой (|). Каждый фильтр компонентов состоит из пары component:value и полностью ограничивает результаты, предоставляемые геокодировщиком. Дополнительные сведения см. в разделе Фильтрация компонентов ниже.

Ответы на запросы геокодирования

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

В примере ниже Google Maps Geocoding 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 Pkwy",
               "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 Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "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 Pkwy</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>San Jose</long_name>
   <short_name>San Jose</short_name>
   <type>administrative_area_level_3</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>Santa Clara</long_name>
   <short_name>Santa Clara</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.4217550</lat>
    <lng>-122.0846330</lng>
   </location>
   <location_type>ROOFTOP</location_type>
   <viewport>
    <southwest>
     <lat>37.4188514</lat>
     <lng>-122.0874526</lng>
    </southwest>
    <northeast>
     <lat>37.4251466</lat>
     <lng>-122.0811574</lng>
    </northeast>
   </viewport>
  </geometry>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </result>
</GeocodeResponse>

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

Поле "status" в объекте ответа службы Geocoding содержит данные о состоянии запроса и может содержать отладочную информацию, позволяющую установить причину ошибки геокодирования. В поле status могут быть указаны следующие значения.


• "OK" – ошибок нет, адрес обработан и получен хотя бы один геокод.
• "ZERO_RESULTS" – геокодирование успешно выполнено, однако результаты не найдены. Это может произойти, если геокодировщику был передан несуществующий адрес (address).
• "OVER_QUERY_LIMIT" – указывает на превышение квоты.
• "REQUEST_DENIED" – указывает на отклонение запроса.
• "INVALID_REQUEST" – как правило, указывает на отсутствие в запросе полей address, components или latlng.
• "UNKNOWN_ERROR" – указывает, что запрос не удалось обработать из-за ошибки сервера. Если повторить попытку, запрос может оказаться успешным.

Сообщения об ошибках

Если геокодировщик возвращает код состояния, отличающийся от OK, в объекте ответа службы Geocoding может быть дополнительное поле error_message. Это поле содержит более подробную информацию о причинах указанного кода состояния.

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

Результаты

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

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

• Массив types[] указывает тип возвращаемого результата. Этот массив содержит набор из нескольких (либо ни одного) тегов, которые определяют тип возвращаемого элемента. Например, геокод "Chicago" возвращает значение "locality", указывающее, что "Chicago" – это город, а также значение "political", указывающее, что это политическая единица.

• formatted_address – строка, содержащая удобочитаемый адрес этого места. Часто это почтовый адрес, который может выглядеть по-разному в зависимости от страны. (В некоторых странах, таких как Великобритания, не разрешено распространение настоящих почтовых адресов в связи с ограничениями лицензирования.) Адрес обычно состоит из одного или нескольких компонентов адреса. Например, "Россия, Москва, Балчуг, 7" содержит отдельные компоненты адреса: "7" (номер дома), "Балчуг" (улица), "Москва" (город) и "Россия" (страна). Эти компоненты адреса содержат дополнительную информацию, как отмечено ниже.

• address_components[] – массив, содержащий отдельные компоненты адреса (см. выше). Каждый address_component, как правило, содержит следующие атрибуты.

  • types[] – массив, указывающий тип компонента адреса.
  • long_name – полное текстовое описание или название компонента адреса, возвращаемого геокодировщиком.
  • short_name – сокращенное текстовое название компонента адреса (если есть). Например, компонент адреса для штата Аляска может содержать значение параметра long_name "Alaska" и short_name "AK" (двухбуквенная почтовая аббревиатура).

  Обратите внимание, что поле address_components[] может содержать больше компонентов адреса, чем указано в поле formatted_address.

• postcode_localities[] – массив всех мест с указанным почтовым индексом. Используется только в том случае, если в качестве результата возвращается почтовый индекс для нескольких мест.

• geometry – содержит следующую информацию:

  • location – геокодированные значения широты и долготы. Как правило, в обычных поисках адресов это поле является наиболее важным.

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

    • "ROOFTOP" – указывает, что возвращаемый результат является точным геокодом, для которого имеется информация о месте с точным почтовым адресом.
    • "RANGE_INTERPOLATED" – указывает, что возвращаемый результат содержит приближенное значение (обычно на дороге), полученное посредством интерполяции двух точных значений (например, перекрестков). Интерполированные результаты обычно возвращаются, если для почтового адреса недоступны геокоды номеров зданий.
    • "GEOMETRIC_CENTER" – указывает на возвращение геометрического центра результата, например, ломаной линии (улицы) или многоугольника (района).
    • "APPROXIMATE" – указывает на возвращение приближенного результата.
  • viewport – содержит рекомендуемую область просмотра возвращаемого результата, которая указывается в виде двух пар значений (широта и долгота), обозначающих юго-западный и северо-восточный углы ограничивающего прямоугольника области просмотра. Как правило, область просмотра используется, чтобы очертить границы результата при его отображении пользователям.
  • bounds (возвращается по желанию) – хранит ограничивающий прямоугольник, который может полностью содержать возвращаемый результат. Эти границы могут не соответствовать рекомендуемой области просмотра. (Например, в состав Москвы входит Зеленоград, который технически является частью города, но не должен отображаться в области просмотра.)
• 

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

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

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

Поскольку точный формат отдельного ответа на запрос Google Maps Geocoding API не гарантируется, не следует полагать, что элементы расположены в абсолютных позициях. (В частности, количество address_components внутри ответа Geocoding API зависит от запрашиваемого адреса и может изменяться со временем.) Вместо этого вы должны выполнить синтаксический анализ ответа и выбрать соответствующие значения с помощью выражений. Дополнительные сведения см. в разделе Синтаксический анализ ответов веб-служб.

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

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

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

• street_address – указывает точный почтовый адрес.
• route – указывает шоссе с названием (например, "US 101").
• intersection – указывает крупные перекрестки, как правило, пересечения двух крупных дорог.
• political – указывает политическую единицу. Чаще всего такой тип используется для обозначения некоторых административных объектов.
• country – указывает государственную политическую единицу и обычно представляет собой тип наивысшего порядка, который возвращается геокодировщиком.
• administrative_area_level_1 – указывает гражданскую единицу первого порядка ниже уровня страны. В США такими административными уровнями являются штаты. Эти административные уровни используются не во всех странах.
• administrative_area_level_2 – указывает гражданскую единицу второго порядка ниже уровня страны. В США такими административными уровнями являются округи. Эти административные уровни используются не во всех странах.
• administrative_area_level_3 – указывает гражданскую единицу третьего порядка ниже уровня страны. Такой тип представляет меньшее административное подразделение. Эти административные уровни используются не во всех странах.
• administrative_area_level_4 – указывает гражданскую единицу четвертого порядка ниже уровня страны. Такой тип представляет меньшее административное подразделение. Эти административные уровни используются не во всех странах.
• administrative_area_level_5 – указывает гражданскую единицу пятого порядка ниже уровня страны. Такой тип представляет меньшее административное подразделение. Эти административные уровни используются не во всех странах.
• colloquial_area – указывает общепринятое альтернативное название единицы.
• locality – указывает политическую единицу в составе города.
• ward – указывает определенный тип округа в Японии, чтобы установить различие между несколькими частями населенного пункта в японском адресе.
• sublocality – указывает гражданскую единицу первого порядка ниже уровня населенного пункта. Для некоторых местоположений возможно предоставление одного из дополнительных типов: от sublocality_level_1 до sublocality_level_5. Каждый уровень ниже населенного пункта является гражданской единицей. Большее значение указывает меньшую географическую область.
• neighborhood – указывает именованный район.
• premise – указывает именованное местоположение, обычно одно или несколько зданий с общепринятым названием.
• subpremise – указывает единицу первого порядка ниже именованного местоположения, обычно одно здание в границах комплекса зданий с общепринятым названием.
• postal_code – указывает почтовый индекс в том виде, в котором он используется в стране для обработки почты.
• natural_feature – указывает важный природный объект.
• airport – указывает аэропорт.
• park – указывает парк с названием.
• point_of_interest – указывает достопримечательность с названием. Как правило, такие достопримечательности являются важными местными единицами, которые не подходят для других категорий, например, небоскреб "Эмпайр-стейт-билдинг" или статуя Свободы.

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

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

Примечание. Этот список не является полным и может изменяться.

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

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

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

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

Например, по геокоду "Воскресенск" обычно возвращается город в Московской области:

Запрос:

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

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Однако при добавлении аргумента bounds, определяющего район Перми, по этому геокоду будет возвращено село в Пермском крае:

Запрос:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles 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" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

Привязка к региону

В ответе геокодирования Google Maps Geocoding API возвращает результаты адресов с учетом региона (как правило, страны), из которого был отправлен запрос. Например, поисковый запрос "Сан-Франциско" может вернуть один результат, если он был отправлен из домена на территории США, и другой – если он был отправлен из Испании.

Вы можете настроить Google Maps Geocoding API на возврат результатов для определенного региона с помощью параметра region. В этом параметре для указания региона используется аргумент ccTLD (домен верхнего уровня кода страны). Большинство кодов ccTLD идентичны кодам ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD для Великобритании выражается как "uk" (.co.uk), а код ISO 3166-1 – как "gb" (применяется для Соединенного Королевства Великобритании и Северной Ирландии).

Результаты геокодирования можно привязать к любому домену, в котором официально используется основное приложение Google Карты. Следует отметить, что указание региона выражает лишь предпочтение результатам для определенного домена. Если за пределами этого домена есть другие результаты, лучше соответствующие критериям, они также могут отображаться.

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

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

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "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" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "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, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

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

В ответе геокодирования Google Maps Geocoding API может возвращать адреса в строго определенном районе. Это ограничение указывается с использованием фильтра components. Фильтр включает в себя список пар component:value, разделяемых вертикальной чертой (|). Возвращаются только результаты, соответствующие всем критериям фильтрации. Значения фильтров поддерживают те же методы исправления орфографии и частичного соответствия, что и другие запросы геокодирования. Если результат геокодирования возвращает частичное совпадение для фильтра компонентов, в ответе он будет содержать поле partial_match.

Для фильтрации могут быть доступны следующие components:

• route – соответствие длинному или короткому названию маршрута.
  
• locality – соответствие обоим типам locality и sublocality.
• administrative_area – соответствие всем уровням administrative_area.
• postal_code – соответствие полям postal_code и postal_code_prefix.
• country – соответствие названию страны или двухбуквенному коду страны ISO 3166-1.

Примечание. Каждый компонент адреса может быть указан либо в параметре адреса, либо в виде фильтра компонентов, но не в обоих этих случаях. При использовании компонента одновременно в адресе и фильтре будет возвращен ответ ZERO_RESULTS.

При геокодировании для города Санта-Круз (Santa Cruz) с использованием параметра components=country:ES будет получен результат для города Санта-Крус-де-Тенерифе (Santa Cruz de Tenerife) на Канарских островах в Испании. Запрос:

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=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" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canarias",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, 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"
}

Запросы с фильтром компонентов вернут только те результаты геокодирования, которые соответствуют критериям фильтра. Если совпадения не найдены, геокодировщик вернет результат, соответствующий самому фильтру. Запрос:

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

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Texas",
               "short_name" : "TX",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Texas, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 36.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "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 можно создать запрос без параметра адреса, но указать компонент без значения нельзя. Запрос:

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

Ответ:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Обратное геокодирование (поиск адреса)

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

Обязательные параметры: В запросе обратного геокодирования необходимо указать один (но не оба) из следующих параметров:

• Либо: latlng – значения широты и долготы, обозначающие место, для которого вам необходимо получить ближайший адрес в понятной человеку форме.
• Либо: placeId – идентификатор места, для которого нужно получить адрес в понятной человеку форме. Это уникальный идентификатор, который можно использовать и с другими интерфейсами Google API. Например, вы можете использовать идентификатор placeId, возвращаемый Google Maps Roads API, для получения адреса фиксированной точки. Подробные сведения об идентификаторах мест см. в соответствующем обзоре. Идентификатор места можно указать только в том случае, если запрос содержит ключ API или идентификатор клиента Google Maps API for Work.

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

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

• key – ключ API вашего приложения, полученный из Google Developers Console. Этот ключ используется для идентификации приложения в целях управления квотами.
• language – язык, на котором выводятся результаты. См. список поддерживаемых языков домена. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным. Если параметр language не указан, геокодировщик будет по возможности использовать основной язык домена, из которого отправлен запрос.
• result_type – один или несколько типов адреса, разделенных вертикальной чертой (|). Примеры типов адреса: country, street_address, postal_code. Полный список допустимых значений представлен в описании типов адреса на этой странице. Указание типа ограничивает результаты только этим типом. Если указаны несколько типов, API вернет все адреса, которые соответствуют любому из этих типов. Примечание. Этот параметр доступен только для тех запросов, которые содержат ключ API или идентификатор клиента.
• location_type – один или несколько типов места, разделенных вертикальной чертой (|). Указание типа ограничивает результаты только этим типом. Если указаны несколько типов, API вернет все адреса, которые соответствуют любому из этих типов. Примечание. Этот параметр доступен только для тех запросов, которые содержат ключ API или идентификатор клиента. Поддерживаются следующие значения:
  • "ROOFTOP" – ограничивает результаты адресами, для которых имеется информация о месте с точным почтовым адресом.
  • "RANGE_INTERPOLATED" – ограничивает результаты теми, которые содержат приближенное значение (обычно на дороге), полученное посредством интерполяции двух точных значений (например, перекрестков). Диапазон результатов интерполяции обычно указывает, что для адреса недоступны геокоды зданий.
  • "GEOMETRIC_CENTER" – ограничивает результаты геометрическими центрами места, например, ломаной линии (улицы) или многоугольника (района).
  • "APPROXIMATE" – ограничивает результаты теми, которые считаются приблизительными.

При использовании обоих ограничений result_type и location_type API вернет только те результаты, которые соответствуют как ограничению result_type, так и location_type.

Обратное геокодирование для широты и долготы

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

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

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

Приведенный выше запрос возвращает следующий результат:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional results[] ...

Обратите внимание, что обратный геокодировщик вернул несколько результатов. Результаты "formatted_address" – это не только почтовые адреса, но также любые варианты географического наименования места. Например, при геокодировании точка в Москве может быть помечена точным адресом, названием города (Москва), области или страны (Россия). Для геокодировщика все эти элементы являются адресами. Обратный геокодировщик возвращает любой из этих типов как действительный результат.

Обратный геокодировщик сопоставляет административные единицы (страны, области, города, районы), адреса и почтовые индексы.

Полный список значений formatted_address, возвращаемых по предыдущему запросу, показан ниже.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

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

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

Обратное геокодирование для идентификатора места

Следующий запрос содержит идентификатор места для одного из мест в Бруклине:

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

Приведенный выше запрос возвращает следующий результат:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Обратное геокодирование с ограничением по типу

В приведенном ниже примере возвращаемые адреса ограничиваются теми, которые имеют тип места ROOFTOP и тип адреса street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Примечание. Эти ограничения действительны только для обратного геокодирования.

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

Формат ответа на запросы обратного геокодирования идентичен формату ответа на запросы обычного геокодирования. См. раздел Ответы на запросы геокодирования. Ниже приведены коды состояния, которые могут содержаться в ответе на запрос обратного геокодирования.

Коды состояния обратного геокодирования

Поле "status" в объекте ответа службы Geocoding содержит данные о состоянии запроса и может содержать отладочную информацию, позволяющую установить причину ошибки обратного геокодирования. В поле status могут быть указаны следующие значения.

• "OK" – ошибок нет, получен хотя бы один адрес.
• "ZERO_RESULTS" – обратное геокодирование успешно выполнено, однако результаты не найдены. Такое может произойти, если геокодировщику были переданы координаты latlng отдаленного места.
• "OVER_QUERY_LIMIT" – указывает на превышение квоты.
• "REQUEST_DENIED" – указывает на отклонение запроса. Это может быть связано с тем, что запрос включает в себя параметры result_type или location_type, но не содержит ключ API или идентификатор клиента.
• "INVALID_REQUEST" – обычно означает одну из следующих причин:
  • Отсутствуют поля запроса (address, components или latlng).
  • Указан недействительный параметр result_type или location_type.
• "UNKNOWN_ERROR" – указывает, что запрос не удалось обработать из-за ошибки сервера. Если повторить попытку, запрос может оказаться успешным.

Параметр sensor

Ранее запросы Google Maps API обязательно должны были содержать параметр sensor, чтобы указать, использовался ли приложением датчик для определения местоположения пользователя. Этот параметр больше не используется.