Configurar a API Geocoding

Este documento descreve as etapas necessárias para começar a usar a API Geocoding.

Os produtos da Plataforma Google Maps exigem que as chamadas de API incluam uma chave de API ou um token OAuth para evitar o uso não autorizado. Você pode escolher o procedimento de configuração que corresponde ao seu ambiente de implantação.

Chave de API Token do OAuth

Criar um token OAuth

A API Geocoding é compatível com o OAuth 2.0 para autenticação. O Google oferece suporte a cenários comuns do OAuth 2.0, como os de um servidor da Web.

Neste documento, descrevemos como transmitir um token OAuth para uma chamada de API Geocoding no seu ambiente de desenvolvimento. Para mais informações sobre como usar o OAuth em um ambiente de produção, consulte Métodos de autenticação no Google.

É possível chamar as APIs do Google Maps diretamente fazendo solicitações de API ao servidor ou usar bibliotecas de cliente para simplificar seu código. O Google Maps oferece bibliotecas de cliente para Go, Java, Node.js e Python. Para mais informações, consulte Bibliotecas de cliente da API Geocoding.

Visão geral do OAuth

É possível criar e gerenciar tokens de acesso com o OAuth de várias maneiras, dependendo do seu ambiente de implantação.

É possível usar o OAuth 2.0 para interações de servidor para servidor entre seu aplicativo e um serviço do Google. Nesse cenário, você usa uma conta de serviço associada ao aplicativo, e não a um usuário individual. É possível fazer solicitações de API usando a conta de serviço sem envolver os usuários diretamente. Para mais informações sobre métodos de autenticação, consulte Métodos de autenticação no Google.

Como alternativa, é possível integrar a API Geocoding a um app móvel Android ou iOS. Para mais informações sobre como usar o OAuth e gerenciar tokens de acesso em diferentes ambientes de implantação, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Escopos do OAuth

Para usar o OAuth com a API Geocoding, atribua ao token o escopo correto. A API Geocoding é compatível com os seguintes escopos:

• https://www.googleapis.com/auth/maps-platform.geocode: use com todos os métodos da API Geocoding.
• https://www.googleapis.com/auth/maps-platform.geocode.address: use apenas com GeocodeAddress para geocodificação direta.
• https://www.googleapis.com/auth/maps-platform.geocode.location: use apenas com GeocodeLocation para geocodificação inversa.
• https://www.googleapis.com/auth/maps-platform.geocode.place: use apenas com GeocodePlace para geocodificação de lugar.

Também é possível usar o escopo geral https://www.googleapis.com/auth/cloud-platform para todos os métodos da API Geocoding. Esse escopo é útil durante o desenvolvimento porque é o padrão ao criar tokens com a CLI gcloud.

Exemplo: testar chamadas da API REST no ambiente de desenvolvimento local

Se você não tiver um ambiente que gere tokens e quiser testar a API Geocoding com um token OAuth, use o procedimento desta seção.

Este exemplo descreve como usar o token do OAuth fornecido pelo Application Default Credentials (ADC) para fazer a chamada. Para mais informações sobre como usar o ADC para chamar APIs do Google com bibliotecas de cliente, consulte Autenticar usando bibliotecas de cliente.

Use o procedimento REST a seguir apenas para desenvolvimento ou teste, não para produção.

Pré-requisitos

Antes de fazer uma solicitação REST usando o ADC, use a CLI gcloud para fornecer credenciais ao ADC:

1. Instale e inicialize a CLI gcloud. Para mais informações, consulte Instalar a CLI gcloud.

2. Faça a autenticação com a gcloud CLI:

   gcloud auth application-default login

3. Conclua o processo de login para salvar suas credenciais no arquivo de credenciais local usado pelo ADC.

Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

Fazer uma solicitação REST

Neste exemplo, você transmite dois cabeçalhos de solicitação:

• Transmita o token OAuth no cabeçalho Authorization usando o seguinte comando para gerar o token:

  gcloud auth application-default print-access-token

  O token retornado tem um escopo de https://www.googleapis.com/auth/cloud-platform.

• Transmita o ID ou o nome do seu projeto na nuvem do Google Cloud com o faturamento ativado no cabeçalho X-Goog-User-Project.

Para chamar a API Geocoding usando um token OAuth, siga estas etapas:

1. No exemplo de código a seguir, substitua PROJECT_ID pelo ID do projeto do 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. Para copiar o comando curl, clique em Copiar no exemplo de código.

3. Cole o comando em uma janela de terminal e execute-o.

Solução de problemas

Se a sua solicitação retornar uma mensagem de erro informando que essa API não é compatível com credenciais do usuário final, consulte Solução de problemas de configuração do ADC.