Configurare l'API Geolocation

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

Prerequisiti

Questa procedura ti guida nella configurazione di un account Google Cloud e di un progetto cloud Google con la fatturazione abilitata. Dovresti anche conoscere le modalità di addebito per l'utilizzo dell'API Geolocation.

1. Esamina la fatturazione e i costi per l'utilizzo in Utilizzo e fatturazione dell'API Geolocation.

2. Verifica di avere un account Google Cloud.

   Accedi alla console Google Cloud
   Nota: se sei un nuovo utente e non hai un account Google Cloud, ovvero non puoi accedere alla console, consulta Inizia a utilizzare Google Maps Platform.

3. Verifica di avere un progetto Google Cloud con la fatturazione abilitata.

   Vai alla pagina Fatturazione
   Nota: se sei un nuovo utente e non hai un progetto Google Cloud, consulta Inizia a utilizzare Google Maps Platform.
1. Seleziona il tuo progetto per aprire la pagina Fatturazione.

2. Nella pagina Fatturazione:

   • Se la fatturazione è già abilitata per il progetto selezionato e hai un solo account di fatturazione, si apre la pagina Fatturazione.
   • Se hai più account di fatturazione, seleziona Vai all'account di fatturazione collegato per visualizzare i dettagli dell'account di fatturazione associato al progetto.
   • Se esiste un account di fatturazione, ma non è associato al progetto, ti verrà chiesto di collegare un account di fatturazione al progetto.
   • Se non esiste un account di fatturazione o se vuoi crearne uno nuovo, seleziona Gestisci account di fatturazione per creare un nuovo account di fatturazione. Per saperne di più, consulta Crea un nuovo account di fatturazione Cloud self-service.

Abilita l'API

Prima di poter utilizzare l'API Geolocation, devi abilitarla nel tuo progetto Google Cloud utilizzando la console Google Cloud o il comando gcloud.

Nota: dopo aver abilitato un'API, potrebbe essere necessario attendere alcuni minuti prima di poter effettuare una richiesta.

Per abilitare l'API:

Console

1. Apri la pagina di prodotto nella console Google Cloud:

   Abilita l'API Geolocation

2. Fai clic sul pulsante Abilita.

   Nota: se l'API è già abilitata, viene visualizzato il pulsante Gestisci anziché Abilita.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "geolocation.googleapis.com"

Scopri di più su Google Cloud SDK, sull'installazione di Cloud SDK e sui seguenti comandi:

• gcloud services enable
• gcloud services disable

Ottieni una chiave API da utilizzare con l'API Geolocation

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

Una chiave API è una stringa alfanumerica univoca che associa il tuo account di fatturazione Cloud e il tuo progetto cloud Google Cloud alla richiesta effettuata dalla tua applicazione a un'API o un SDK di Google Maps Platform. Per creare una nuova chiave o aggiungere un'API o un SDK a una chiave esistente, segui queste istruzioni.

Console

1. Vai alla pagina Google Maps Platform > Chiavi e credenziali.

   Vai alla pagina Chiavi e credenziali

2. Se richiesto, seleziona il progetto.

3. Procedi in uno dei seguenti modi:

   • Crea una nuova chiave:

     1. Fai clic su Crea credenziali > Chiave API.
     2. Nel riquadro Crea chiave API, apri l'elenco Seleziona limitazioni dell'API.
     3. Cancella tutte le API che non sono necessarie per questa chiave e assicurati che l'API Geolocation rimanga selezionata.
     4. Fai clic su Crea. Nel riquadro viene visualizzata la nuova chiave API.

   • Utilizza una chiave esistente:

     1. Fai clic sul nome della chiave.
     2. Nell'elenco Seleziona limitazioni dell'API, seleziona API Geolocation.
     3. Fai clic su Salva.

   La selezione di un'API qui non la abilita. Assicurati che l'API Geolocation sia abilitata nella relativa pagina della libreria API.

4. Per visualizzare la stringa della chiave in un secondo momento, vai alla pagina Chiavi e credenziali e fai clic su Mostra chiave per la chiave.

Se la console ha un aspetto diverso da questi passaggi, consulta Crea una chiave API e Aggiungi limitazioni API nella documentazione di Google Cloud.

gcloud

Sostituisci PROJECT_ID con l'ID progetto nei comandi seguenti.

• Crea una nuova chiave: esegui il comando seguente e sostituisci DISPLAY_NAME con un nome per la chiave.

  gcloud services api-keys create \
      --project="PROJECT_ID" \
      --display-name="DISPLAY_NAME" \
      --api-target=service=geolocation.googleapis.com

  Scopri di più su Google Cloud SDK, sull'installazione di Cloud SDK e sui seguenti comandi:

  • gcloud services api-keys create

• Utilizza una chiave esistente: esegui il comando seguente e sostituisci KEY_ID con l'ID della chiave. Il flag --append mantiene le API già consentite dalla chiave. In caso contrario, il comando le sostituisce.

  gcloud services api-keys update KEY_ID \
      --project="PROJECT_ID" \
      --append \
      --api-target=service=geolocation.googleapis.com

  Scopri di più su Google Cloud SDK, sull'installazione di Cloud SDK e sui seguenti comandi:

  • gcloud services api-keys update
  • gcloud services api-keys list

  L'ID chiave non è la stringa della chiave o il nome visualizzato. Per trovarlo, esegui gcloud services api-keys list --project="PROJECT_ID". L'ID è l'ultima parte del campo name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

Per visualizzare la stringa della chiave, esegui gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

Effettua una richiesta API

Effettua una richiesta API Geolocation per restituire una risposta JSON contenente la posizione sotto forma di coordinate di latitudine e longitudine. Devi includere la stringa alfanumerica della chiave API in ogni richiesta e utilizzare HTTPS per le richieste che includono la chiave API.

1. Fai clic su API_KEY nel codice di seguito per inserire la stringa alfanumerica della chiave:

   curl -X POST -d '{
     "considerIp": "false",
     "wifiAccessPoints": [
       {
         "macAddress": "3c:37:86:5d:75:d4",
         "signalStrength": -35,
         "signalToNoiseRatio": 0
       },
       {
         "macAddress": "30:86:2d:c4:29:d0",
         "signalStrength": -35,
         "signalToNoiseRatio": 0
       }
     ]
   }' \
   -H 'Content-Type: application/json' \
   -H 'X-Goog-Api-Key:YOUR_API_KEY' \
   'https://www.googleapis.com/geolocation/v1/geolocate'
   

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 nel formato:

{
  "location": {
    "lat": 37.4241247,
    "lng": -122.0915703
  },
  "accuracy": 20
}

Applica le limitazioni relative alle chiavi API

Attenzione: una chiave API senza restrizioni può essere utilizzata per effettuare una richiesta a qualsiasi servizio di Google Maps Platform, inclusa l'API Geolocation. Sei responsabile dal punto di vista finanziario degli addebiti causati dall'abuso di chiavi API senza limitazioni.

Google consiglia vivamente di limitare le chiavi API limitandone l'utilizzo solo alle API e alle app che ne hanno bisogno. La limitazione delle chiavi API aggiunge sicurezza alla tua applicazione proteggendola da richieste ingiustificate. Le chiavi API supportano due tipi di limitazioni:

• Le restrizioni delle API specificano quali SDK e API possono essere chiamati utilizzando la chiave API. La console e gcloud CLI richiedono almeno una restrizione API quando crei una chiave.
• Le restrizioni delle applicazioni specificano i siti web, gli indirizzi IP o le app che possono utilizzare una chiave API.

Per saperne di più sull'applicazione delle limitazioni, consulta Limita le chiavi API.

Passaggi successivi

Ora che hai abilitato l'API Geolocation e inviato una richiesta con esito positivo, consulta Richieste e risposte di geolocalizzazione per scoprire di più sull'utilizzo dell'API.