Для методов Geocoding API v4 по умолчанию установлено ограничение в 25 запросов в секунду (QPS). Информацию о запросе увеличения квоты см. в разделе «Просмотр и управление квотами» и выберите Geocoding API в качестве службы.

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

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

Разработчики из Европейской экономической зоны (ЕЭЗ)

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

При обратном геокодировании местоположения в ответе содержится следующее:

Идентификатор места адреса
Плюс-коды адреса
Адресные данные

Этот API возвращает адреса различных типов, от самых точных адресов улиц до менее точных политических образований, таких как районы, города, округа и штаты. Наиболее точный адрес, как правило, является первым результатом. Если вы хотите найти адрес определенного типа, используйте параметр types .

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

Запрос обратного геокодирования — это HTTP GET-запрос. Вы можете указать местоположение в виде неструктурированной строки :

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

Или в виде структурированного набора координат широты и долготы, представленных параметрами запроса:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

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

Все остальные параметры передавайте в качестве параметров URL или, для таких параметров, как ключ API или маска поля, в заголовках в рамках GET-запроса. Например:

Передайте неструктурированную строку местоположения.

Неструктурированное местоположение — это местоположение, представленное в виде строки координат широты и долготы, разделенных запятыми:

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

Или в команде curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

Пройдите через структурированное место

Укажите структурированное местоположение, используя параметр запроса location типа LatLng . Объект LatLng позволяет указывать широту и долготу в качестве отдельных параметров запроса:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Используйте OAuth для отправки запроса.

API геокодирования версии 4 поддерживает аутентификацию OAuth 2.0 . Для использования OAuth с API геокодирования необходимо присвоить токену OAuth правильную область действия (scope). API геокодирования поддерживает следующие области действия для использования с обратным геокодированием:

https://www.googleapis.com/auth/maps-platform.geocode — Использовать со всеми методами API геокодирования.
https://www.googleapis.com/auth/maps-platform.geocode.location — Используйте только с GeocodeLocation для обратного геокодирования.

Кроме того, вы можете использовать общую область видимости https://www.googleapis.com/auth/cloud-platform для всех методов API геокодирования. Эта область видимости полезна во время разработки, но не в продакшене, поскольку это общая область видимости, предоставляющая доступ ко всем методам.

Для получения дополнительной информации и примеров см. раздел «Использование OAuth» .

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

Обратное геокодирование возвращает объект GeocodeLocationResponse , содержащий:

Массив results , состоящий из объектов GeocodeResult , представляющих данное место.
В ответах API геокодирования массивы types содержатся в двух основных местах внутри объекта GeocodeResult :
1. GeocodeResult.types : Этот массив указывает общий тип(ы) результата. Возможные значения берутся из таблиц A и B на странице «Типы мест (новые)».
2. GeocodeResult.addressComponents[].types : Каждый компонент адреса имеет массив types , указывающий тип конкретной части адреса. Эти значения берутся из таблицы типов адресов и типов компонентов адреса на странице «Типы мест (новые)».
Обратный геокодер возвращает более одного результата в массиве results . Результаты представляют собой не только почтовые адреса, но и любые способы географического обозначения местоположения. Например, при геокодировании точки в городе Чикаго, геокодированная точка может быть обозначена как адрес улицы, как город (Чикаго), как штат (Иллинойс) или как страна (Соединенные Штаты). Все это является «адресами» для геокодера. Обратный геокодер возвращает любой из этих типов в качестве допустимых результатов.
Поле plusCode типа PlusCode содержит код Plus, наиболее точно соответствующий широте и долготе в запросе. Кроме того, каждый элемент массива results содержит код Plus. Расстояние между декодированным кодом Plus и точкой запроса составляет менее 10 метров.
Примечание: API не всегда возвращает Plus-коды.

Полный JSON-объект имеет следующий вид:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Необходимые параметры

расположение
Укажите координаты широты и долготы, чтобы определить ближайший, удобочитаемый адрес.

Дополнительные параметры

languageCode
Язык, на котором будут возвращаться результаты.
- См. список поддерживаемых языков . Google часто обновляет список поддерживаемых языков, поэтому этот список может быть неполным.
- Если languageCode не указан, API по умолчанию использует en . Если вы укажете недопустимый код языка, API вернет ошибку INVALID_ARGUMENT .
- API делает все возможное, чтобы предоставить уличный адрес, понятный как пользователю, так и местным жителям. Для достижения этой цели он возвращает уличные адреса на местном языке, при необходимости транслитерированные в письменность, понятную пользователю, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на одном языке, который выбирается из первого компонента.
- Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
- Предпочитаемый язык оказывает незначительное влияние на набор результатов, которые API выбирает для возврата, и на порядок их возврата. Геокодер по-разному интерпретирует сокращения в зависимости от языка, например, сокращения для типов улиц или синонимы, которые могут быть допустимы в одном языке, но не в другом.
regionCode
Региональный код представляет собой двухсимвольное значение кода CLDR . Значение по умолчанию отсутствует. Большинство кодов CLDR идентичны кодам ISO 3166-1.
При геокодировании адреса ( прямое геокодирование ) этот параметр может влиять на результаты работы сервиса, но не ограничивать их полностью указанным регионом. При геокодировании местоположения ( обратное геокодирование или геокодирование места ) этот параметр может использоваться для форматирования адреса. Во всех случаях этот параметр может влиять на результаты в соответствии с действующим законодательством.
детализация
Указывается одна или несколько уровней детализации местоположения в качестве отдельных параметров запроса, как определено в Granularity . Если указано несколько параметров granularity , API вернет все адреса, соответствующие любому из уровней детализации.
Параметр granularity не ограничивает поиск указанной гранулярностью местоположения. Вместо этого granularity действует как фильтр после поиска. API получает все результаты для указанного location , а затем отбрасывает те результаты, которые не соответствуют указанной гранулярности местоположения.
Если вы укажете и types , и granularity , API вернет только те результаты, которые соответствуют обоим параметрам. Например:
```
https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY
```
типы
Один или несколько типов адресов, указанных в качестве отдельных параметров запроса. Возможные значения берутся из таблицы « Типы адресов и типы компонентов адресов» на странице «Типы мест (новые)». Если вы укажете несколько параметров types , API вернет все адреса, соответствующие любому из типов.
Параметр types не ограничивает поиск указанными типами адресов. Вместо этого types выступает в качестве фильтра после поиска. API получает все результаты для указанного местоположения, а затем отбрасывает те результаты, которые не соответствуют указанным типам адресов.
Если вы укажете и types , и granularity , API вернет только те результаты, которые соответствуют обоим параметрам. Например:
```
https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY
```
FieldMask
Создайте маску полей ответа , чтобы указать поля, которые должны быть возвращены в ответе. Передайте маску полей ответа методу, используя параметр URL $fields или fields , или используя HTTP-заголовок X-Goog-FieldMask . Например, приведенный ниже запрос вернет только поля placeID из ответа.
```
curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
```
Ответ таков:
```
{
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}
```
Дополнительные сведения см. в разделе «Выберите поля для возврата» .
Важно: маскирование полей — это хорошая практика проектирования, позволяющая избежать запроса лишних данных и, следовательно, сэкономить время на обработке.

Обратное геокодирование местоположения Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

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

Передайте неструктурированную строку местоположения.

Пройдите через структурированное место

Используйте OAuth для отправки запроса.

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

Необходимые параметры

расположение

Дополнительные параметры

languageCode

regionCode

детализация

типы

FieldMask

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