Configurare l'API Geocoding

Sviluppatori dello Spazio economico europeo (SEE)

Se il tuo indirizzo di fatturazione si trova nello Spazio economico europeo, a partire dall'8 luglio 2025, i Termini di servizio di Google Maps Platform per il SEE si applicheranno al tuo utilizzo dei servizi. La funzionalità varia in base alla regione. Scopri di più.

Questo documento descrive i passaggi necessari per iniziare a utilizzare l'API Geocoding.

1. Account e fatturazione Assicurati di soddisfare i prerequisiti.

2. Abilita l'API Attiva l'API nel tuo progetto Google Cloud.

3. Effettua la tua prima richiesta Configura una chiave API o OAuth per effettuare una richiesta API autenticata.

Punto chiave: questa guida alla configurazione include la procedura per configurare una chiave API e creare un token OAuth. Scegli la procedura applicabile al tuo ambiente di deployment.

I prodotti Google Maps Platform sono protetti dall'utilizzo non autorizzato richiedendo che le chiamate API includano una chiave API o un token OAuth.

Chiave API Token OAuth

Crea un token OAuth

L'API Geocoding supporta l'utilizzo di OAuth 2.0 per l'autenticazione. Google supporta gli scenari OAuth 2.0 comuni, ad esempio quelli per un server web.

Questo documento descrive come trasmettere un token OAuth alla chiamata dell'API Geocoding nel tuo ambiente di sviluppo. Per istruzioni sull'utilizzo di OAuth in un ambiente di produzione, consulta Metodi di autenticazione di Google.

Nota:

Sebbene tu possa utilizzare le API Google Maps direttamente effettuando richieste API al server, le librerie client forniscono semplificazioni che riducono notevolmente la quantità di codice da scrivere. Google Maps fornisce librerie client per molti linguaggi di programmazione, tra cui Go, Java, Node.js e Python.

Consulta le librerie client dell'API Geocoding per documentazione ed esempi.

Informazioni su OAuth

Esistono molti modi per creare e gestire token di accesso con OAuth in base al tuo ambiente di deployment.

Ad esempio, il sistema Google OAuth 2.0 supporta le interazioni server-to-server, come quelle tra la tua applicazione e un servizio Google. Per questo scenario è necessario un service account, ovvero un account che appartiene alla tua applicazione anziché a un singolo utente finale. La tua applicazione chiama le API di Google per conto del service account, quindi gli utenti non sono direttamente coinvolti. Per saperne di più sui metodi di autenticazione, vedi Metodi di autenticazione di Google.

In alternativa, puoi utilizzare l'API Geocoding come parte di un'app mobile per Android o iOS. Per informazioni generali sull'utilizzo di OAuth con l'API Geocoding, incluse quelle sulla gestione dei token di accesso per diversi ambienti di deployment, consulta l'articolo Utilizzare OAuth 2.0 per accedere alle API di Google.

Informazioni sugli ambiti OAuth

Per utilizzare OAuth con l'API Geocoding, al token OAuth deve essere assegnato l'ambito corretto. L'API Geocoding supporta i seguenti ambiti:

• https://www.googleapis.com/auth/maps-platform.geocode — Utilizza con tutti gli endpoint dell'API Geocoding.
• https://www.googleapis.com/auth/maps-platform.geocode.address — Utilizza solo con GeocodeAddress per il geocoding diretto.
• https://www.googleapis.com/auth/maps-platform.geocode.location — Utilizza solo con GeocodeLocation per la geocodifica inversa.
• https://www.googleapis.com/auth/maps-platform.geocode.place — Utilizza solo con GeocodePlace per la geocodifica dei luoghi.

Inoltre, puoi utilizzare l'ambito https://www.googleapis.com/auth/cloud-platform generale per tutti gli endpoint dell'API Geocoding. Questo ambito è utile durante lo sviluppo perché è l'ambito predefinito utilizzato durante la creazione di token utilizzando gcloud.

Esempio: prova le chiamate API REST nel tuo ambiente di sviluppo locale

Se vuoi provare l'API Geocoding utilizzando un token OAuth, ma non hai configurato un ambiente per generare token, puoi utilizzare la procedura descritta in questa sezione per effettuare la chiamata.

Questo esempio descrive come utilizzare il token OAuth fornito da Credenziali predefinite dell'applicazione (ADC) per effettuare la chiamata. Per informazioni sull'utilizzo di ADC per chiamare le API di Google utilizzando le librerie client, consulta Autenticarsi utilizzando le librerie client.

Nota: la procedura seguente per effettuare una chiamata REST non è destinata all'uso in un ambiente di produzione. Utilizza questa procedura solo per un ambiente di sviluppo o di test.

Prerequisiti

Prima di poter effettuare una richiesta REST utilizzando ADC, utilizza Google Cloud CLI per fornire le credenziali ad ADC:

1. Installa e inizializza gcloud CLI.

2. Esegui il seguente comando gcloud sulla tua macchina locale per creare il file delle credenziali:

   gcloud auth application-default login

3. Viene visualizzata una schermata di accesso. Dopo aver eseguito l'accesso, le tue credenziali vengono archiviate nel file delle credenziali locali utilizzato da ADC.

Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

Effettuare una richiesta REST

In questo esempio, vengono trasmesse due intestazioni della richiesta:

• Passa il token OAuth nell'intestazione Authorization utilizzando il seguente comando per generare il token:

  gcloud auth application-default print-access-token

  Il token restituito ha un ambito di https://www.googleapis.com/auth/cloud-platform.

• Trasferisci l'ID o il nome del tuo progetto Google Cloud per cui è attivata la fatturazione nell'intestazione X-Goog-User-Project.

L'esempio seguente effettua una chiamata all'API Geocoding utilizzando un token OAuth.

1. Modifica il campo PROJECT_ID per trasmettere l'ID del tuo progetto 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. Fai clic sull'icona di copia nell'esempio di codice, , per copiare il comando curl.
3. Incolla il comando in una finestra del terminale ed eseguilo.

La risposta è un oggetto JSON:

Risoluzione dei problemi

Se la richiesta restituisce un messaggio di errore relativo alle credenziali dell'utente finale non supportate da questa API, consulta Risolvere i problemi di configurazione di ADC.