Configurar a API Geocoding

Desenvolvedores do Espaço Econômico Europeu (EEE)

Se o endereço de faturamento estiver localizado no Espaço Econômico Europeu, a partir de 8 de julho de 2025 seu uso dos serviços estará sujeito aos Termos de Serviço do EEE da Plataforma Google Maps. A funcionalidade varia de acordo com a região. Saiba mais.

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

1. Conta e faturamento Verifique se você atende aos pré-requisitos.

2. Ativar a API Ative a API no seu projeto na nuvem do Google Cloud.

3. Faça sua primeira solicitação Configure uma chave de API ou o OAuth para fazer uma solicitação de API autenticada.

Ponto principal: este guia de configuração inclui o procedimento para configurar uma chave de API e criar um token OAuth. Escolha o procedimento aplicável ao seu ambiente de implantação.

Para proteger os produtos da Plataforma Google Maps contra uso não autorizado, as chamadas de API precisam incluir uma chave de API ou um token OAuth.

Chave de API Token OAuth

Criar um token OAuth

A API Geocoding aceita o uso do 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.

Este documento descreve como transmitir um token OAuth para a chamada de API Geocoding no seu ambiente de desenvolvimento. Para instruções sobre como usar o OAuth em um ambiente de produção, consulte Métodos de autenticação no Google.

Observação:

Embora seja possível usar as APIs do Google Maps diretamente fazendo solicitações de API ao servidor, as bibliotecas de cliente oferecem simplificações que reduzem significativamente a quantidade de código que você precisa escrever. O Google Maps oferece bibliotecas de cliente para muitas linguagens de programação, incluindo Go, Java, Node.js e Python.

Consulte as bibliotecas de cliente da API Geocoding para acessar a documentação e exemplos.

Sobre o OAuth

Há muitas maneiras de criar e gerenciar tokens de acesso com o OAuth com base no seu ambiente de implantação.

Por exemplo, o sistema Google OAuth 2.0 oferece suporte a interações de servidor para servidor, como as que ocorrem entre seu aplicativo e um serviço do Google. Para esse cenário, você precisa de uma conta de serviço, que é uma conta que pertence ao aplicativo e não a um usuário final individual. O aplicativo chama as APIs do Google em nome da conta de serviço, para que os usuários não sejam envolvidos diretamente. Para mais informações sobre métodos de autenticação, consulte Métodos de autenticação no Google.

Como alternativa, você pode usar a API Geocoding como parte de um app para dispositivos móveis Android ou iOS. Para informações gerais sobre como usar o OAuth com a API Geocoding, incluindo informações sobre como gerenciar tokens de acesso para diferentes ambientes de implantação, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Sobre os escopos do OAuth

Para usar o OAuth com a API Geocoding, o token OAuth precisa receber o escopo correto. A API Geocoding oferece suporte aos 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.

Além disso, você pode 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 escopo padrão usado ao criar tokens usando gcloud.

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

Se você quiser testar a API Geocoding usando um token OAuth, mas não tiver uma configuração de ambiente para gerar tokens, use o procedimento nesta seção para fazer a chamada.

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

Observação: o procedimento abaixo para fazer uma chamada REST não se destina ao uso em um ambiente de produção. Use esse procedimento apenas para um ambiente de desenvolvimento ou teste.

Pré-requisitos

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

1. Instale e inicialize a CLI gcloud.

2. Execute o comando gcloud a seguir na máquina local para criar o arquivo de credenciais:

   gcloud auth application-default login

3. Uma tela de login será exibida. Após o login, suas credenciais são armazenadas 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 comando a seguir 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 projeto na nuvem do Google Cloud que tem o faturamento ativado no X-Goog-User-Project cabeçalho.

O exemplo a seguir faz uma chamada para a API Geocoding usando um token OAuth.

1. Edite o campo PROJECT_ID para transmitir o ID do seu projeto na nuvem do Google.

   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. Clique no ícone de cópia no exemplo de código, , para copiar o comando curl.
3. Cole o comando em uma janela de terminal e execute-o.

A resposta é um objeto JSON:

Solução de problemas

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