Настройте API геокодирования

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

Если ваш платежный адрес находится в Европейской экономической зоне, то с 8 июля 2025 года к использованию вами Услуг будут применяться Условия предоставления услуг платформы Google Maps для стран ЕЭЗ . Функциональность различается в зависимости от региона. Подробнее .

В этом документе описаны шаги, необходимые для начала использования API геокодирования.

1. Учетная запись и выставление счетов Убедитесь, что вы соответствуете всем предварительным требованиям.

2. Включите API. Включите API в своем проекте Google Cloud.

3. Сделайте свой первый запрос. Для выполнения аутентифицированных запросов к API необходимо настроить ключ API или использовать OAuth.

Важный момент: данное руководство по настройке включает в себя процедуру как для настройки ключа API , так и для создания токена OAuth . Выберите процедуру, подходящую для вашей среды развертывания.

Продукты платформы Google Maps защищены от несанкционированного использования за счет того, что вызовы API должны включать либо ключ API , либо токен OAuth .

API-ключ, токен OAuth

Создайте токен OAuth.

API геокодирования поддерживает использование OAuth 2.0 для аутентификации. Google поддерживает распространенные сценарии OAuth 2.0, например, для веб-сервера.

В этом документе описывается, как передать токен OAuth в вызов API геокодирования в вашей среде разработки . Инструкции по использованию OAuth в производственной среде см. в разделе «Методы аутентификации» на сайте Google .

Примечание:

Хотя вы можете использовать API Google Maps напрямую, отправляя запросы к серверу, клиентские библиотеки упрощают задачу и значительно сокращают объем необходимого кода. Google Maps предоставляет клиентские библиотеки для многих языков программирования, включая Go, Java, Node.js и Python.

См. раздел «Библиотеки клиента API геокодирования» для получения документации и примеров.

О протоколе OAuth

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

Например, система Google OAuth 2.0 поддерживает взаимодействие между серверами, например, между вашим приложением и сервисом Google. Для этого сценария вам потребуется сервисный аккаунт, который принадлежит вашему приложению, а не отдельному конечному пользователю. Ваше приложение вызывает API Google от имени сервисного аккаунта, поэтому пользователи напрямую не участвуют в процессе. Дополнительную информацию о методах аутентификации см. в разделе «Методы аутентификации в Google» .

В качестве альтернативы вы можете использовать API геокодирования в составе мобильного приложения для Android или iOS. Общую информацию об использовании OAuth с API геокодирования, включая информацию об управлении токенами доступа для различных сред развертывания, см. в разделе «Использование OAuth 2.0 для доступа к API Google» .

О сферах действия OAuth

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

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

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

Пример: Попробуйте выполнить вызовы REST API в вашей локальной среде разработки.

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

В этом примере описывается, как использовать токен OAuth, предоставляемый Application Default Credentials (ADC), для выполнения вызова. Информацию об использовании ADC для вызова API Google с помощью клиентских библиотек см. в разделе «Аутентификация с помощью клиентских библиотек» .

Примечание : Приведенная ниже процедура выполнения REST-запроса не предназначена для использования в производственной среде. Используйте эту процедуру только в среде разработки или тестирования.

Предварительные требования

Прежде чем отправлять REST-запросы через ADC, воспользуйтесь интерфейсом командной строки Google Cloud, чтобы предоставить ADC учетные данные:

1. Установите и инициализируйте интерфейс командной строки gcloud .

2. Выполните следующую команду gcloud на локальном компьютере, чтобы создать файл учетных данных:

   gcloud auth application-default login

3. Отображается экран входа в систему. После входа в систему ваши учетные данные сохраняются в локальном файле учетных данных, используемом ADC .

Для получения дополнительной информации см. раздел «Настройка АЦП для локальной среды разработки» .

Отправьте REST-запрос

В этом примере вы передаете два заголовка запроса:

• Передайте токен OAuth в заголовке Authorization , используя следующую команду для генерации токена:

  gcloud auth application-default print-access-token

  Возвращенный токен имеет область действия https://www.googleapis.com/auth/cloud-platform.

• Передайте идентификатор или название вашего проекта Google Cloud, в котором включена оплата, в заголовке X-Goog-User-Project .

В следующем примере выполняется вызов API геокодирования с использованием токена OAuth.

1. Отредактируйте поле PROJECT_ID , чтобы передать идентификатор вашего проекта Google Cloud.

   curl -X GET -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. Нажмите на значок копирования в примере кода. чтобы скопировать команду curl .
3. Вставьте команду в окно терминала и выполните её.

В ответ приходит JSON-объект:

Поиск неисправностей

Если ваш запрос возвращает сообщение об ошибке, указывающее на то, что учетные данные конечного пользователя не поддерживаются этим API, см. раздел «Устранение неполадок при настройке АЦП» .