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
. Un key
è il
chiave API. Questa chiave identifica l'applicazione ai fini della quota
gestione dei dispositivi. 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 vengono restituiti in base all'indirizzo IP della località della richiesta. I seguenti campi sono supportati e sono tutti 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 per la rete di casa del dispositivo.
Questa è l'MNC per GSM, WCDMA, LTE e NR. Il CDMA utilizza l'ID 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 . |
Questo campo è facoltativo, ma deve essere sempre incluso se il tipo di opzione radio è
noti al cliente. Se il campo viene omesso, l'API Geolocation sarà gsm per impostazione predefinita,
che genera risultati non validi o pari a zero se il presunto tipo di radio è
risposta errata. |
carrier |
string |
Il nome del corriere. | |
considerIp |
boolean |
Specifica se eseguire il fallback alla geolocalizzazione IP se gli indicatori Wi-Fi e delle torri di telefonia mobile mancano, sono vuoti o non sono sufficienti per stimare la posizione del dispositivo. | Il valore predefinito è true . Imposta considerIp su
false per evitare il fallback. |
cellTowers |
array |
Una serie di oggetti delle torri cellulari. | Consulta la sezione Oggetti torre di telefonia mobile di seguito. |
wifiAccessPoints |
array |
Una serie di oggetti del punto di accesso Wi-Fi. | Consulta la sezione Oggetti punto di accesso Wi-Fi di seguito. |
Di seguito è riportato 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 torre di telefonia cellulare.
Campo | Tipo JSON | Descrizione | Note |
---|---|---|---|
cellId |
number (uint32 ) |
Identificatore univoco della cella. | Obbligatorio per radioType gsm (predefinito), cdma ,
wcdma e lte ; rifiutato per nr .Consulta la sezione Calcolo di cellId riportata di seguito, che elenca anche gli intervalli di valori validi per ogni tipo di opzione. |
newRadioCellId |
number (uint64 ) |
Identificatore univoco della cella NR (5G). | Obbligatorio per radioType nr ; rifiutato per altri
di testo.Consulta la sezione Calcolo di newRadioCellId riportata di seguito. che elenca anche l'intervallo di valori valido per il campo. |
locationAreaCode |
number (uint32 ) |
Il codice area geografica (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 altri valori.Intervallo valido con gsm , cdma , wcdma e
lte : 0-65535.Esempio di intervallo valido con nr : 0-16777215. |
mobileCountryCode |
number (uint32 ) |
Il Mobile Country Code (Centro clienti) del ripetitore di telefonia mobile. | Obbligatorio per radioType gsm (predefinito), wcdma ,
lte e nr ; non utilizzato per cdma .Intervallo valido: 0-999. |
mobileNetworkCode |
number (uint32 ) |
Il codice di rete mobile della torre cellulare.
Si tratta dell'MNC per GSM, WCDMA, LTE e NR. CDMA utilizza l'ID 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 dall'ultimo aggiornamento della cella principale. | Se l'età è 0, cellId o newRadioCellId rappresenta un valore attuale
misurazione. |
signalStrength |
number (double ) |
Intensità del segnale radio misurata in dBm. | |
timingAdvance |
number (double ) |
La in anticipo valore. |
Calcolo di cellId
in corso...
I tipi di radio precedenti a NR (5G) utilizzano il campo cellId
a 32 bit per trasmettere l'ID 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 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 numero intero a 28 bit
concatenando l'identificatore del Radio Network Controller Identifier (RNC-ID) a 12-bit e
ID cella (CID).
Formula:rnc_id << 16 | cid
.
Intervallo valido: 0-268435455.
Nota: se specifichi solo il valore dell'ID cella a 16 bit nelle reti WCDMA, i risultati saranno errati o pari a zero. - Le reti LTE (4G) utilizzano E-UTRAN Cell Identity (ECI), che è un valore intero a 28 bit
concatenando l'identificatore B del nodo E-UTRAN a 20 bit (eNBId) e l'ID della 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, non è corretto o non genera alcun risultato.
L'inserimento di valori al di fuori di questi intervalli nella richiesta API potrebbe causare un comportamento indefinito. L'API,
a discrezione di Google, può troncare il numero in modo che rientri nell'intervallo documentato, dedurre una
correzione a radioType
o restituisci un risultato NOT_FOUND
senza
indicatore nella risposta.
Di seguito è riportato un esempio di oggetto torre di telefonia mobile LTE.
{ "cellTowers": [ { "cellId": 170402199, "locationAreaCode": 35632, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, "timingAdvance": 15 } ] }
Calcolo in corso
newRadioCellId
Le reti più recenti, i cui ID cella sono più lunghi di 32 bit, utilizzano il campo newRadioCellId
di 64 bit per trasmettere l'ID cella di rete all'API Geolocation.
- Le reti NR (5G) utilizzano l'identità della nuova cella radio (NCI) a 36 bit così com'è.
Intervallo valido: 0-68719476735.
Di seguito è riportato un esempio di oggetto NR di colonne.
{ "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 che rappresentano fisicamente distinti
dispositivi punto di accesso. 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 BSS, BSSID o indirizzo MAC. |
Obbligatorio.Stringa esadecimale separata da due punti (: ).
Solo amministrato universalmente Gli indirizzi MAC possono essere individuati tramite l'API. Altri indirizzi MAC sono eliminati automaticamente e può far sì che una richiesta API diventi efficace vuoto. Per maggiori dettagli, vedi Eliminare punti di accesso Wifi inutili. |
signalStrength |
number (double ) |
L'intensità del segnale attuale misurata in dBm. | Per i punti di accesso Wi-Fi, i valori dBm sono in genere -35 o inferiori 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/rumore corrente misurato in dB. |
Di seguito è riportato un esempio di oggetto punto di accesso Wi-Fi.
{ "macAddress": "f0:d5:bf:fd:12:ae", "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": "30:86:2d:c4:29:d0", "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.4241173, "lng": -122.0915717 }, "accuracy": 20 }
Eliminazione dei punti di accesso Wi-Fi inutilizzati
Rimozione degli oggetti del punto di accesso Wi-Fi con macAddress
che sono
amministrata localmente
può migliorare la percentuale di successo delle chiamate API Geolocation che utilizzano il Wi-Fi come input.
Se, dopo l'applicazione di filtri, è possibile stabilire che una chiamata all'API di geolocalizzazione non andrà a buon fine, è possibile utilizzare misure di mitigazione come l'utilizzo di indicatori di posizione precedenti o di AP Wi-Fi con indicatori più deboli. Si tratta di un compromesso tra
necessità dell'applicazione di una stima della posizione, oltre alla sua precisione e richiamo
i tuoi requisiti. Le seguenti tecniche di filtraggio mostrano come filtrare gli input, ma non mostrano le mitigazioni che, in qualità di ingegnere delle applicazioni, puoi scegliere di applicare.
Gli indirizzi MAC gestiti localmente non sono indicatori di posizione utili per l'API e vengono rimossi silenziosamente dalle richieste. Puoi rimuovere questi indirizzi MAC
assicurandoti che il secondo bit meno significativo del
byte più significativo di macAddress
sia 0
, ad esempio il
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 verrebbe
escluso da questo filtro.
L'intervallo di indirizzi MAC tra 00:00:5E:00:00:00
e
00:00:5E:FF:FF:FF
sono
prenotato
per IANA e spesso utilizzata per la gestione della rete e le funzioni multicast
che ne precludono l'uso come segnale di posizione. Dovresti rimuovere anche questi
gli 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');
L'applicazione di questo filtro comporta che nell'elenco rimangano solo 1c:34:56:78:9a:bc
. Poiché questo elenco contiene
meno di 2 indirizzi MAC Wi-Fi, il
non riesce e viene visualizzato un errore HTTP 404
(notFound
)
di Google Cloud.
Risposte di geolocalizzazione
Una richiesta di geolocalizzazione riuscita restituisce una risposta in formato JSON. definire una località e un raggio.
location
: le coordinate di latitudine e longitudine stimate dell'utente in gradi. Contiene un sottocampolat
e un sottocampolng
.accuracy
: la precisione della posizione stimata, in metri. Rappresenta il raggio di un cerchio intorno a una datalocation
.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }