Richieste di geolocalizzazione
Le richieste di geolocalizzazione vengono inviate tramite 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
. 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 nel formato JSON. Se non viene incluso il corpo della richiesta, i risultati vengono restituiti in base all'indirizzo IP della località della richiesta. I seguenti campi sono supportati e tutti i campi sono facoltativi, se non diversamente specificato:
Campo | Tipo JSON | Descrizione | Note |
---|---|---|---|
homeMobileCountryCode |
number (uint32 ) |
Il codice paese del dispositivo mobile (Centro clienti) della 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 è l'MNC per GSM, WCDMA, LTE e NR. Il CDMA utilizza l'ID di sistema (SID) |
Intervallo valido per MNC: 0-999. Intervallo valido per SID: 0-32767. |
radioType |
string |
Il tipo di segnale radio mobile. I valori supportati sono gsm , cdma , wcdma , lte e nr . |
Anche se questo campo è facoltativo, deve essere sempre incluso se il tipo di opzione è noto al client. Se il campo viene omesso, l'API Geolocation è impostata in modo predefinito su gsm ,
il che riporterà risultati non validi o pari a zero se il tipo di opzione presunto è
errato. |
carrier |
string |
Il nome dell'operatore. | |
considerIp |
boolean |
Consente di specificare se ricorrere alla geolocalizzazione dell'IP se i segnali Wi-Fi e delle torri cellulari mancano, vuoti o non sufficienti per stimare la posizione del dispositivo. | Il valore predefinito è true . Imposta considerIp su
false per evitare il fallback. |
cellTowers |
array |
Un array di oggetti delle torri cellulari. | Consulta la sezione Oggetti delle torri cellulari di seguito. |
wifiAccessPoints |
array |
Un array di oggetti di punti di accesso Wi-Fi. | Consulta la sezione Oggetti punti di accesso Wi-Fi di seguito. |
Di seguito è mostrato un esempio di corpo della richiesta 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 delle 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 (valore predefinito), 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 gli 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 prefisso locale (LAC) per le reti GSM e WCDMA. L'ID rete (NID) per le reti CDMA. Il codice dell'area di monitoraggio (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) del ripetitore di telefonia mobile. | Obbligatorio per radioType gsm (valore predefinito), wcdma , lte e nr ; non utilizzato per cdma .Intervallo valido: 0-999. |
mobileNetworkCode |
number (uint32 ) |
Il codice di rete mobile del ripetitore di telefonia mobile.
Si tratta dell'MNC per GSM, WCDMA, LTE e NR. Il CDMA utilizza l'ID di sistema (SID). |
Obbligatorio. Intervallo valido per MNC: 0-999. Intervallo valido per SID: 0-32767. |
I seguenti campi facoltativi non vengono utilizzati, ma possono essere inclusi se sono disponibili valori.
Campo | Tipo JSON | Descrizione | Note |
---|---|---|---|
age |
number (uint32 ) |
Il numero di millisecondi da quando questa cella era primaria. | Se l'età è 0, cellId o newRadioCellId rappresenta una misurazione attuale. |
signalStrength |
number (double ) |
Intensità del segnale radio misurata in dBm. | |
timingAdvance |
number (double ) |
Il valore dell'anticipo nei tempi. |
Calcolo di cellId
in corso...
I tipi di radio precedenti agli errori NR (5G) utilizzano il campo cellId
a 32 bit per passare l'ID cella di rete all'API Geolocation.
- Le reti GSM (2G) utilizzano il Cell ID (CID) a 16 bit così com'è. Intervallo valido: 0-65535.
- Le reti CDMA (2G) utilizzano l'ID stazione di base a 16 bit (bid) così com'è. Intervallo valido: 0-65535.
- Le reti WCDMA (3G) utilizzano la Cell Identity (UC-ID) UTRAN/GERAN, ovvero un valore intero a 28 bit che concatena l'RNC-ID (Radio Network Controller Identifier) a 12 bit e l'ID cella a 16 bit.
Formula:rnc_id << 16 | cid
.
Intervallo valido: 0-268435455.
Nota: se specifichi solo il valore di Cell ID a 16 bit nelle reti WCDMA, i risultati non saranno corretti o non riceverai alcun risultato. - Le reti LTE (4G) utilizzano E-UTRAN Cell Identity (ECI), un valore intero a 28 bit che concatena l'identificatore di nodo B E-UTRAN a 20 bit (eNBId) e l'ID cella a 8 bit (CID).
Formula:enb_id << 8 | cid
.
Intervallo valido: 0-268435455.
Nota: se specifichi solo il valore di Cell ID a 8 bit nelle reti LTE, i risultati non saranno corretti o non verranno mostrati risultati.
L'inserimento di valori al di fuori di questi intervalli nella richiesta API può comportare un comportamento indefinito. L'API,
a discrezione di Google, potrebbe troncare il numero in modo che rientri nell'intervallo documentato, dedurre
una correzione a radioType
o restituire un risultato NOT_FOUND
senza
alcun indicatore nella risposta.
Di seguito è riportato un esempio di oggetto della torre cellulare LTE.
{ "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 di cella sono più lunghi di 32 bit, utilizzano il campo newRadioCellId
a 64 bit per passare l'ID cella di rete all'API Geolocation.
- Le reti NR (5G) utilizzano l'NCI (New Radio Cell Identity) a 36 bit così com'è.
Intervallo valido: 0-68719476735.
Di seguito è riportato un esempio di oggetto della torre cellulare NR.
{ "cellTowers": [ { "newRadioCellId": 68719476735, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, } ] }
Oggetti punti di accesso Wi-Fi
L'array wifiAccessPoints
del corpo della richiesta deve contenere due o più oggetti del 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 è chiamato indirizzo BSS, BSSID o MAC. |
Obbligatorio. Stringa esadecimale separata da due punti (: ).
Solo gli indirizzi MAC amministrati universalmente possono essere individuati tramite l'API. Altri indirizzi MAC vengono automaticamente eliminati e potrebbe comportare la mancanza di una richiesta API. Per maggiori dettagli, consulta la pagina Rilasciare punti di accesso Wi-Fi inutili. |
signalStrength |
number (double ) |
L'intensità del segnale attuale misurata in dBm. | Per i punti di accesso Wi-Fi, i valori in dBm sono generalmente uguali o inferiori a -35 e sono compresi tra -128 e -10 dBm. Accertati 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 tramite il quale il cliente comunica con il punto di accesso. | |
signalToNoiseRatio |
number (double ) |
Il rapporto tra segnale e rumore attuale misurato in dB. |
Di seguito è mostrato un esempio di oggetto punto di accesso Wi-Fi.
{ "macAddress": "9c:1c:12:b0:45:f1", "signalStrength": -43, "signalToNoiseRatio": 0, "channel": 11, "age": 0 }
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 precedenti è simile alla seguente:
{ "location": { "lat": 37.4241876, "lng": -122.0917381 }, "accuracy": 32.839 }
Caduta di punti di accesso Wi-Fi inutilizzati
La rimozione degli oggetti dei punti di accesso Wi-Fi con macAddress
amministrati localmente
può migliorare la percentuale di successo delle chiamate API Geolocation che utilizzano il Wi-Fi come input.
Se, dopo l'applicazione dei filtri, è possibile determinare che una chiamata all'API Geolocation non ha esito positivo, è possibile utilizzare misure di mitigazione come l'utilizzo di segnali di posizione meno recenti o di AP Wi-Fi con segnali più deboli. Questo approccio rappresenta un compromesso tra l'esigenza dell'applicazione di avere una stima della località e i suoi requisiti di precisione e richiamo. Le seguenti tecniche di filtro mostrano come filtrare gli input, ma non mostrano le mitigazioni che potresti scegliere di applicare in qualità di Application Engineer.
Gli indirizzi MAC amministrati localmente non sono indicatori di posizione utili per l'API e vengono automaticamente esclusi dalle richieste. Puoi rimuovere questi indirizzi MAC assicurandoti che il secondo bit meno significativo del byte più significativo di macAddress
sia 0
, ad esempio 2
in 02:00:00:00:00:00
. L'indirizzo MAC di trasmissione (FF:FF:FF:FF:FF:FF
) è un esempio di indirizzo MAC che potrebbe essere opportunamente escluso da questo filtro.
L'intervallo di indirizzi MAC compreso tra 00:00:5E:00:00:00
e
00:00:5E:FF:FF:FF
è
riservato
a IANA e spesso viene utilizzato per la gestione della rete e le funzioni multicast
che ne precludono l'utilizzo come indicatore di posizione. Dovresti anche rimuovere questi indirizzi MAC dagli input all'API.
Ad esempio, gli indirizzi MAC utilizzabili per la geolocalizzazione possono essere raccolti da un
array di stringhe macAddress
denominate macs
:
String[] macs = {"12:34:56:78:9a:bc", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"}; ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs)); _macs.removeIf(m -> !(0 == (2 & Integer.parseInt(m.substring(1, 2), 16)) && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'] macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']; macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16)) && m.substr(0, 8).toUpperCase() !== '00:00:5E');
Se utilizzi questo filtro, nell'elenco rimangono solo 1c:34:56:78:9a:bc
. Poiché questo elenco ha meno di 2 indirizzi MAC Wi-Fi, la richiesta non andrà a buon fine e verrà restituita una risposta(notFound
) HTTP 404.
Risposte di geolocalizzazione
Una richiesta di geolocalizzazione riuscita restituisce una risposta in formato JSON che definisce una località e un raggio.
location
: le coordinate di latitudine e longitudine stimate dell'utente, in gradi. Contiene un campo secondariolat
e un campo secondariolng
.accuracy
: la precisione della posizione stimata, espressa in metri. Rappresenta il raggio di un cerchio intorno all'elementolocation
specificato.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }