Questa pagina è stata tradotta dall'API Cloud Translation.

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": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "94:b4:0f:fd:c1:40",
      "signalStrength": -35,
      "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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

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.