Для методов Geocoding API версии 4 по умолчанию установлена квота 25 запросов в секунду. Информацию о том, как запросить увеличение квоты, можно найти в статье Просмотр квот и управление ими. В качестве сервиса выберите Geocoding API.

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

Начало работы с Geocoding API v4

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

Geocoding API версии 4 предоставляет два основных набора функций: поиск пунктов назначения по подробным гиперлокальным атрибутам и базовое геокодирование (преобразование координат в адреса). Не знаете, какой метод выбрать? Подробнее о том, как выбрать метод геокодирования…

Поиск пунктов назначения (SearchDestinations). Получение подробных сведений о пункте назначения, включая входы в здания, точки навигации, контуры зданий и территорий, подпункты назначения и ближайшие ориентиры.
Геокодирование (GeocodeAddress). Преобразует почтовые адреса в координаты широты и долготы, чтобы разместить основные маркеры или центрировать карту.
Обратное геокодирование (GeocodeLocation). Преобразует географические координаты в человекочитаемый почтовый адрес.
Геокодирование места (GeocodePlace). Поиск форматированного адреса и координат по известному идентификатору места.

Примеры запросов и ответов

Доступ к Geocoding API осуществляется через HTTP-интерфейс. Ниже приведены примеры быстрого начала работы с поиском пунктов назначения, прямым геокодированием и обратным геокодированием.

Запрос и ответ для поиска пунктов назначения (гиперлокальные данные о прибытии)

В следующем примере отправляется HTTP-запрос POST к SearchDestinations для адреса "1600 Amphitheatre Parkway, Mountain View, CA". Обратите внимание, что для SearchDestinations требуется заголовок X-Goog-FieldMask, в котором указаны поля, которые нужно вернуть:

curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "1600 Amphitheatre Parkway, Mountain View, CA"
  }
}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.formattedAddress,destinations.primary.location,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/destinations"

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

{
  "destinations": [
    {
      "primary": {
        "displayName": { "text": "Googleplex", "languageCode": "en" },
        "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
        "location": { "latitude": 37.4220656, "longitude": -122.0840897 },
        "displayPolygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [-122.084958, 37.422145],
              [-122.084112, 37.422610],
              [-122.083510, 37.421980],
              [-122.084958, 37.422145]
            ]
          ]
        }
      },
      "entrances": [
        {
          "location": { "latitude": 37.422189, "longitude": -122.084215 },
          "tags": ["PREFERRED"]
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "Eg...",
          "displayName": { "text": "Amphitheatre Pkwy Dropoff", "languageCode": "en" },
          "location": { "latitude": 37.421912, "longitude": -122.084301 },
          "travelModes": ["DRIVE"],
          "usages": ["DROPOFF", "PICKUP"]
        }
      ],
      "landmarks": [
        {
          "place": { "displayName": { "text": "Charleston Park", "languageCode": "en" } },
          "relationalDescription": { "text": "Adjacent to Charleston Park", "languageCode": "en" },
          "straightLineDistanceMeters": 85.4
        }
      ]
    }
  ]
}

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

В следующем примере запрашиваются широта и долгота для адреса "1600 Amphitheatre Parkway, Mountain View, CA" и указывается, что выходные данные должны быть в формате JSON.

curl -H "X-Goog-Api-Key: YOUR_API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Чтобы проверить это, введите URL в браузере (не забудьте заменить YOUR_API_KEY своим ключом API). Ответ включает широту и долготу адреса.

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

Ниже приведен пример ответа геокодирования в формате JSON:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "placeId": "ChIJ2Z2idB66j4ARI43TG-9RoCQ",
      "location": {
        "latitude": 37.4438238,
        "longitude": -122.0869895
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4424748197085,
          "longitude": -122.0883384802915
        },
        "high": {
          "latitude": 37.445172780291493,
          "longitude": -122.08564051970852
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "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"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

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

В примере ниже запрашивается адрес, соответствующий заданной широте и долготе в Бруклине (Нью-Йорк, США). В нем указывается, что ответ должен быть в формате JSON.

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

Чтобы проверить это, введите URL в адресную строку браузера (не забудьте заменить YOUR_API_KEY на свой ключ API). Ответ содержит человекочитаемый адрес для местоположения, заданного широтой и долготой.

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

Ниже приведен пример ответа обратного геокодирования в формате JSON:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE",
      "location": {
        "latitude": 37.4225657,
        "longitude": -122.08465439999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421214719708509,
          "longitude": -122.08603273029148
        },
        "high": {
          "latitude": 37.423912680291508,
          "longitude": -122.0833347697085
        }
      },
      "bounds": {
        "low": {
          "latitude": 37.4225178,
          "longitude": -122.08484599999998
        },
        "high": {
          "latitude": 37.422609600000008,
          "longitude": -122.0845215
        }
      },
      "formattedAddress": "Google Building 40, 1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "Google Building 40",
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "Google Building 40",
          "shortText": "Google Building 40",
          "types": [
            "premise"
          ],
          "languageCode": "en"
        },
        {
          "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",
        "subpremise"
      ]
    },
    ... Additional results truncated in this example[] ...
}

Аутентификация, квоты, цены и правила

Аутентификация

Чтобы использовать Geocoding API, сначала нужно включить его и получить учетные данные для аутентификации. Подробнее см. в разделе Начало работы с платформой Google Карт.

Квоты и цены

Подробную информацию о квотах и ценах для Geocoding API можно найти на странице Использование и оплата.

Правила

Geocoding API необходимо использовать в соответствии с правилами API.