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
è la chiave API dell'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 viene incluso, 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 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 (impostazione predefinita),
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.
Questo è l'MNC per GSM, WCDMA, LTE e NR. 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 . |
Sebbene questo campo sia facoltativo, deve essere sempre incluso se il tipo di opzione radio è noto al client. Se il campo viene omesso, l'impostazione predefinita dell'API Geolocation sarà gsm ,
il che ridurrà risultati non validi o pari a zero se il tipo di opzione presunto è
errato. |
carrier |
string |
Il nome dell'operatore. | |
considerIp |
boolean |
Specifica se ricorrere alla geolocalizzazione degli IP se i segnali del Wi-Fi e delle torri cellulari mancano, sono vuoti o non sono sufficienti per stimare la posizione del dispositivo. | Il valore predefinito è true . Imposta considerIp su
false per evitare i video di riserva. |
cellTowers |
array |
Una serie di oggetti delle torri cellulari. | Consulta la sezione Oggetti delle torri cellulari 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 delle torri cellulari.
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 di seguito, in cui sono elencati 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
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 di località (LAC) per le reti GSM e WCDMA. L'ID rete (NID) per le reti CDMA. Il codice TAC (Tracking Area Code) per le reti LTE e NR. |
Obbligatorio per radioType gsm (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 (predefinito), wcdma ,
lte e nr ; non utilizzato per cdma .Intervallo valido: 0-999. |
mobileNetworkCode |
number (uint32 ) |
Il codice di rete mobile della torre cellulare.
Questo è l'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 da quando questa cella è 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'avanzamento temporale. |
Calcolo di cellId
in corso...
I tipi di segnali radio precedenti a NR (5G) utilizzano il campo cellId
a 32 bit per trasmettere l'ID cella della 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 a 16 bit (BID) così com'è. Intervallo valido: 0–65535.
- Le reti WCDMA (3G) utilizzano UTRAN/GERAN Cell Identity (UC-ID), ovvero un valore intero a 28 bit che concatena l'identificatore della radio Network Controller Identifier (RNC-ID) a 12 bit e l'ID cella (CID) 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 saranno errati o pari a zero. - Le reti LTE (4G) utilizzano E-UTRAN Cell Identity (ECI), ovvero un valore intero a 28 bit che concatena l'identificatore E-UTRAN del nodo B (eNBId) a 20 bit e l'ID cella (CID) a 8 bit.
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 saranno errati o pari a zero.
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 al valore radioType
o restituire un risultato NOT_FOUND
senza alcun
indicatore nella risposta.
Di seguito è riportato un esempio di oggetto di un ripetitore di telefonia mobile 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 cella sono più lunghi di 32 bit, utilizzano il campo newRadioCellId
a 64 bit per passare l'ID cella della rete all'API Geolocation.
- Le reti NR (5G) utilizzano New Radio Cell Identity (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. 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 (: ).
Tramite l'API è possibile individuare solo gli indirizzi MAC amministrati universalmente. Altri indirizzi MAC vengono eliminati automaticamente e una richiesta API potrebbe diventare effettivamente vuota. Per maggiori dettagli, consulta la sezione Scartare 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 ) |
L'attuale rapporto segnale-rumore 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 una 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
La rimozione degli oggetti del punto 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 del filtro, si può determinare che una chiamata all'API Geolocation
non ha esito positivo, è possibile adottare misure di mitigazione come l'utilizzo di indicatori di posizione meno recenti o punti di accesso Wi-Fi con
segnali più deboli. Questo approccio è un compromesso tra l'esigenza dell'applicazione di una stima della posizione 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 eliminati automaticamente 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 escluso utilmente da questo filtro.
L'intervallo di indirizzi MAC tra 00:00:5E:00:00:00
e
00:00:5E:FF:FF:FF
è
riservato
per IANA e spesso è utilizzato per la gestione della rete e le funzioni multicast
che ne precludono l'utilizzo come indicatore di posizione. Devi anche rimuovere questi
indirizzi MAC dagli input nell'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 rimarrà solo 1c:34:56:78:9a:bc
. Poiché questo elenco contiene
meno di 2 indirizzi MAC Wi-Fi, la richiesta non ha esito positivo e viene restituita una risposta HTTP 404
(notFound
).
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 sottocampolat
e unlng
.accuracy
: la precisione della posizione stimata, in metri. Rappresenta il raggio di un cerchio intorno alocation
specificato.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }