Panoramica

Introduzione

L'API Geolocation restituisce la posizione e il raggio di precisione in base alle informazioni sulle torri cellulari e sui nodi Wi-Fi che il client di telefonia mobile può rilevare. Questo documento descrive il protocollo utilizzato per inviare questi dati al server e restituire una risposta al client.

La comunicazione avviene tramite HTTPS utilizzando POST. Sia la richiesta che la risposta sono formattate come JSON e il tipo di contenuti di entrambi è application/json.

Prima di iniziare

Prima di iniziare a sviluppare con l'API Geolocation, rivedi i requisiti di autenticazione (devi avere una chiave API) e le informazioni su utilizzo e fatturazione dell'API (devi abilitare la fatturazione sul tuo progetto).

Richieste di geolocalizzazione

Le richieste di geolocalizzazione vengono inviate utilizzando POST al seguente URL:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Devi specificare una chiave nella richiesta, inclusa come valore di un parametro key. Un key è la chiave API della tua applicazione. Questa chiave identifica l'applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.

Corpo della richiesta

Il corpo della richiesta deve essere formattato come JSON. Se il corpo della richiesta non è incluso, i risultati verranno restituiti in base all'indirizzo IP della località della richiesta. I seguenti campi sono supportati e tutti i campi sono facoltativi, se non diversamente indicato:

Campo Tipo JSON Descrizione Note
homeMobileCountryCode number (uint32) Il codice paese del dispositivo mobile (Centro clienti) per la rete di casa del dispositivo. Supportato per radioType gsm (valore predefinito), wcdma, lte e nr; non utilizzato per cdma.
Intervallo valido: 0-999.
homeMobileNetworkCode number (uint32) Il codice di rete mobile della rete di casa del dispositivo. Questo è il MNC per GSM, WCDMA, LTE e NR.
CDMA utilizza l'ID di sistema (SID)
Intervallo valido per MNC: 0-999.
Intervallo valido per SID: 0-32767.
radioType string Il tipo di radio su dispositivo mobile. I valori supportati sono gsm, cdma, wcdma, lte e nr. Questo campo è facoltativo, ma deve essere sempre incluso se il tipo di radio è noto al client.
Se il campo viene omesso, l'API Geolocation viene impostata su gsm per impostazione predefinita, il che risulterà non risultati validi o zero se il tipo di radio presumeto è errato.
carrier string Il nome dell'operatore.
considerIp boolean Consente di specificare se utilizzare la geolocalizzazione IP se il segnale Wi-Fi e delle torri cellulari non è indicato, è vuoto o non è sufficiente per stimare la posizione del dispositivo. Il valore predefinito è true. Imposta considerIp su false per disabilitare i contenuti di riserva.
cellTowers array Vari oggetti di torri cellulari. Consulta la sezione Oggetti Torre cellulare di seguito.
wifiAccessPoints array Un array di oggetti punto di accesso Wi-Fi. Consulta la sezione Oggetti punto di accesso Wi-Fi di seguito.

Di seguito è riportato un esempio di corpo dell'API Geolocation.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "gsm",
  "carrier": "Vodafone",
  "considerIp": true,
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

Oggetti torri cellulari

L'array cellTowers del corpo della richiesta contiene zero o più oggetti della torre cellulare.

Campo Tipo JSON Descrizione Note
cellId number (uint32) Identificatore univoco della cella. Obbligatorio per radioType gsm (impostazione predefinita), cdma, wcdma e lte; rifiutato per nr.
Consulta la sezione Calcolo dell'ID cella di seguito, che elenca anche gli intervalli di valori validi per ciascun tipo di opzione.
newRadioCellId number (uint64) Identificatore univoco della cella NR (5G). Obbligatorio per radioType nr; rifiutato per altri tipi.
Consulta la sezione Calcolo di newRadioCellId di seguito, che elenca anche l'intervallo di valori valido per il campo.
locationAreaCode number (uint32) Il codice LAC (Location Area Code) per le reti GSM e WCDMA.
L'ID di rete (NID) per le reti CDMA.
Il monitoraggio dell'area di riferimento (TAC) per le reti LTE e NR.
Obbligatorio per radioType gsm (valore predefinito) e cdma, facoltativo per gli altri valori.
Intervallo valido con gsm, cdma, wcdma e lte: 0-65535.
Intervallo valido con nr: 0-16777215.
mobileCountryCode number (uint32) Il Mobile Country Code (Centro clienti) della torre cellulare. Obbligatorio per radioType gsm (impostazione predefinita), wcdma, lte e nr; non utilizzato per cdma.
Intervallo valido: 0-999.
mobileNetworkCode number (uint32) Il codice di rete mobile della torre cellulare. Questo è il MNC per GSM, WCDMA, LTE e NR.
CDMA utilizza l'ID di sistema (SID).
Obbligatorio.
Intervallo valido per la rete multicanale: 0-999.
Intervallo valido per SID: 0-32767.

I seguenti campi facoltativi non sono attualmente utilizzati, ma possono essere inclusi se i valori sono disponibili.

Campo Tipo JSON Descrizione Note
age number (uint32) Il numero di millisecondi da cui questa cella era primaria. Se l'età è 0, cellId o newRadioCellId rappresentano una misurazione attuale.
signalStrength number (double) Intensità del segnale radio misurata in dBm.
timingAdvance number (double) Il valore tempo di avanzamento.

Calcolo di cellId in corso...

I tipi di radio precedenti a NR (5G) utilizzano il campo cellId a 32 bit per passare l'ID della cella di rete all'API Geolocation.

  • Le reti GSM (2G) utilizzano l'ID cella (CID) a 16 bit così com'è. Intervallo valido: 0-65535.
  • Le reti CDMA (2G) utilizzano l'ID stazione di base (BID) a 16 bit così com'è. Intervallo valido: 0-65535.
  • Le reti WCDMA (3G) utilizzano l'identità cellulare UTRAN/GERAN (UC-ID), che è un valore intero a 28 bit che concatena l'identificatore di rete radio (RNC-ID) a 12 bit e l'ID cellulare a 16 bit.
    Formula: rnc_id << 16 | cid.
    Intervallo valido: 0-268435455.
    Nota: se specifichi solo il valore ID cella a 16 bit nelle reti WCDMA, i risultati non saranno corretti o saranno pari a zero.
  • Le reti LTE (4G) utilizzano E-UTRAN Cell Identity (ECI), che è un valore intero a 28 bit che concatena l'identificatore di nodo E-UTRAN (eNBId) a 20 bit e l'ID cella a 8 bit (CID).
    Formula: enb_id << 8 | cid.
    Intervallo valido: 0-268435455.
    Nota: se specifichi solo il valore ID cella a 8 bit nelle reti LTE, i risultati non saranno corretti o saranno pari a zero.

L'inserimento di valori al di fuori di questi intervalli nella richiesta API potrebbe causare un comportamento non definito. L'API, a discrezione di Google, potrebbe troncare il numero in modo che rientri nell'intervallo documentato, dedurre una correzione rispetto a radioType o restituire un risultato NOT_FOUND senza alcun indicatore nella risposta.

Di seguito è riportato un oggetto torre cellulare LTE di esempio.

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

Calcolo di newRadioCellId in corso...

Le reti più recenti, i cui ID cella sono più lunghi di 32 bit, utilizzano il campo newRadioCellId a 64 bit per passare l'ID della rete di rete all'API Geolocation.

  • Le reti NR (5G) utilizzano la nuova radiocellulare (NCI) a 36 bit così com'è.
    Intervallo valido: 0-68719476735.

Di seguito è riportato un oggetto torrione di esempio NR.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

Oggetti punto di accesso Wi-Fi

L'array wifiAccessPoints del corpo della richiesta deve contenere due o più oggetti punto di accesso Wi-Fi. macAddress è obbligatorio; tutti gli altri campi sono facoltativi.

Campo Tipo JSON Descrizione Note
macAddress string L'indirizzo MAC del nodo Wi-Fi. In genere, si chiama indirizzo BSS, BSSID o MAC. Obbligatorio. :, stringa esadecimale separata.
signalStrength number (double) L'intensità del segnale attuale misurata in dBm. Per i punti di accesso Wi-Fi, i valori dBm sono in genere pari o inferiori a -35 e vanno da -128 a -10 dBm. Assicurati di includere il segno meno.
age number (uint32) Il numero di millisecondi da quando è stato rilevato questo punto di accesso.
channel number (uint32) Il canale su cui il client comunica con il punto di accesso.
signalToNoiseRatio number (double) Il rapporto segnale/corrente attuale misurato in dB.

Di seguito è riportato un oggetto punto di accesso Wi-Fi di esempio.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Risposte di geolocalizzazione

Una richiesta di geolocalizzazione completata restituirà una risposta in formato JSON che definisce una località e un raggio.

  • location: latitudine e longitudine stimate dell'utente, in gradi. Contiene un sottocampo lat e un lng.
  • accuracy: precisione della posizione stimata, in metri. Rappresenta il raggio di un cerchio intorno al location specificato.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Errori

In caso di errore, verrà restituito un corpo di risposta di errore di formato standard e il codice di stato HTTP sarà impostato su uno stato di errore.

La risposta contiene un oggetto con un singolo oggetto error con le seguenti chiavi:

  • code: corrisponde allo stato HTTP della risposta.
  • message: una breve descrizione dell'errore.
  • errors: un elenco degli errori che si sono verificati. Ogni errore contiene un identificatore per il tipo di errore (reason) e una breve descrizione (message).

Ad esempio, l'invio di un file JSON non valido restituirà il seguente errore:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

I possibili errori includono:

Motivo Dominio Codice di stato HTTP Descrizione
dailyLimitExceeded usageLimits 403 Hai superato il limite giornaliero.
keyInvalid usageLimits 400 La chiave API non è valida per l'API Geolocation. Assicurati di aver incluso l'intera chiave e di aver acquistato l'API o di aver attivato la fatturazione e attivato l'API per ottenere la quota senza costi aggiuntivi.
userRateLimitExceeded usageLimits 403 Hai superato il limite di richieste che hai configurato in Google Cloud Console. Questo limite è generalmente impostato come richieste giornaliere, richieste ogni 100 secondi e richieste ogni 100 secondi per utente. Questo limite deve essere configurato per impedire a un singolo o piccolo gruppo di utenti di esaurire la quota giornaliera, permettendo comunque un ragionevole accesso a tutti gli utenti. Consulta la sezione Utilizzo dell'API Capping per configurare questi limiti.
notFound geolocation 404 La richiesta era valida, ma non sono stati restituiti risultati.
parseError global 400 Il corpo della richiesta non è JSON valido. Fai riferimento alla sezione Corpo della richiesta per i dettagli su ciascun campo.

Richieste di esempio

Se vuoi provare l'API Geolocation con dati di esempio, salva il seguente JSON in un file:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "84:d4:7e:f6:99:64",
      "signalStrength": -54,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f6:99:71",
      "signalStrength": -43,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f7:21:35",
      "signalStrength": -32,
      "signalToNoiseRatio": 0
    }
  ]
}

Puoi quindi utilizzare cURL per effettuare la richiesta dalla riga di comando:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

La risposta per gli indirizzi Mac di cui sopra ha il seguente aspetto:

{
  "location": {
      "lat": 37.4237423,
      "lng": -122.0915814
  },
  "accuracy": 20
}

Se non disponi di una chiave API, consulta la sezione Ottenere una chiave API.

Per altri test, puoi raccogliere informazioni dal tuo dispositivo Android usando l'SDK Places per Android e le API Android Location e dal tuo dispositivo iOS usando l'SDK Places per iOS.

Domande frequenti

Perché vedo un raggio accuracy molto ampio nella risposta di geolocalizzazione?

Se la tua risposta di geolocalizzazione mostra un valore molto elevato nel campo accuracy, il servizio potrebbe essere geolocalizzato in base all'IP della richiesta, anziché ai punti di accesso Wi-Fi o alle torri cellulari. Ciò può accadere se non sono presenti torri o punti di accesso validi.

Per confermare che questo sia il problema, imposta considerIp su false nella tua richiesta. Se la risposta è un 404, hai verificato che i tuoi oggetti wifiAccessPoints e cellTowers non possono essere geolocalizzati.