Как настроить Geocoding API

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

Требования

В этом разделе рассказывается, как настроить аккаунт Google Cloud и облачный проект с включенными платежными функциями. Также необходимо знать, как взимается плата за использование Geocoding API.

1. Ознакомьтесь с информацией о тарифах и оплате в статье Использование и оплата Geocoding API.

2. Убедитесь, что у вас есть аккаунт Google Cloud.

   Войдите в консоль Google Cloud.

3. Убедитесь, что у вас есть проект Google Cloud с включенными платежными функциями.

   Перейти на страницу "Оплата"
1. Выберите проект, чтобы открыть страницу Billing (Оплата).

2. На странице Оплата:

   • Если для выбранного проекта уже включена оплата и у вас только один платежный аккаунт, откроется страница Оплата.
   • Если у вас несколько платежных аккаунтов, нажмите Открыть этот аккаунт. Появится страница с информацией о платежном аккаунте, связанном с проектом.
   • Если у вас есть платежный аккаунт, но он не связан с проектом, вам будет предложено связать их.
   • Если у вас нет платежного аккаунта или вы хотите создать новый, выберите Manage Billing Accounts (Управление платежными аккаунтами). Подробнее о том, как создать платежный аккаунт Cloud для самостоятельного использования…

Включение API

Прежде чем использовать Geocoding API, необходимо включить его в проекте Google Cloud с помощью консоли Google Cloud или команды gcloud.

Чтобы включить API, выполните следующие действия:

gcloud services enable \
    --project "PROJECT" \
    "geocoding-backend.googleapis.com"

Получите ключ API для использования с Geocoding API.

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

Ключ API – это уникальная буквенно-цифровая строка, которая связывает ваш платежный аккаунт Cloud и облачный проект Google Cloud с запросом, который ваше приложение отправляет в API или SDK платформы Google Карт. Чтобы создать ключ или добавить API или SDK к существующему ключу, следуйте инструкциям ниже.

Как отправить запрос к API

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

1. Нажмите API_KEY в коде ниже, чтобы вставить буквенно-цифровую строку ключа:

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

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

Вы получите объект JSON следующего вида:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJxQvW8wK6j4AR3ukttGy3w2s",
      "placeId": "ChIJxQvW8wK6j4AR3ukttGy3w2s",
      "location": {
        "latitude": 37.4224119,
        "longitude": -122.08550779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420886519708496,
          "longitude": -122.08713963029149
        },
        "high": {
          "latitude": 37.423584480291495,
          "longitude": -122.0844416697085
        }
      },
      "formattedAddress": "Google Building 41, 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": "Google Building 41",
          "shortText": "Google Building 41",
          "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"
          ]
        },
        {
          "longText": "1351",
          "shortText": "1351",
          "types": [
            "postal_code_suffix"
          ]
        }
      ],
      "types": [
        "premise",
        "street_address"
      ]
    }
  ]
}

Как применить ограничения для ключа API

Мы настоятельно рекомендуем ограничивать использование ключей API только теми API и приложениями, которым они необходимы. Ограничение ключей API повышает безопасность вашего приложения, защищая его от нежелательных запросов. Для ключей API поддерживаются два типа ограничений:

• Ограничения API определяют, какие SDK и API можно вызывать с помощью ключа API. При создании ключа в консоли или gcloud CLI необходимо задать хотя бы одно ограничение API.
• Ограничения для приложений определяют, какие сайты, IP-адреса или приложения могут использовать ключ API.

Подробнее о том, как ограничить использование ключей API…

Как создать токен OAuth

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

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

Вы можете вызывать Google Maps API напрямую, отправляя запросы к API на сервер, или использовать клиентские библиотеки, чтобы упростить код. Google Карты предоставляют клиентские библиотеки для Go, Java, Node.js и Python. Подробнее о клиентских библиотеках Geocoding API…

Общая информация о протоколе OAuth

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

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

Вы также можете интегрировать Geocoding API в мобильное приложение для Android или iOS. Подробнее о том, как использовать OAuth и управлять токенами доступа в разных средах развертывания, читайте в статье Использование OAuth 2.0 для доступа к API Google.

Области действия OAuth

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

• https://www.googleapis.com/auth/maps-platform.geocode – используется со всеми методами Geocoding API.
• https://www.googleapis.com/auth/maps-platform.destinations – используйте только с SearchDestinations для запросов о пункте назначения и прибытии.
• 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 для всех методов Geocoding API. Эта область действия полезна при разработке, поскольку она используется по умолчанию при создании токенов с помощью CLI gcloud.

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

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

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

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

Требования

Прежде чем отправлять REST-запрос с помощью ADC, предоставьте ADC учетные данные, используя CLI gcloud:

1. Установите и инициализируйте интерфейс командной строки gcloud. Подробнее о том, как установить gcloud CLI…

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

   gcloud auth application-default login

3. Завершите процесс входа, чтобы сохранить учетные данные в локальном файле учетных данных, используемом ADC.

Подробнее о том, как настроить ADC для локальной среды разработки…

Как выполнить запрос REST

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

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

  gcloud auth application-default print-access-token

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

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

Чтобы вызвать Geocoding 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/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. Чтобы скопировать команду curl, нажмите Копировать в примере кода.

3. Вставьте команду в окно терминала и запустите ее.

Устранение неполадок

Если в ответ на запрос вы получаете сообщение об ошибке о том, что API не поддерживает учетные данные конечных пользователей, ознакомьтесь с разделом Устранение неполадок с настройкой ADC.