Richiesta di risposta e geolocalizzazione

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. key è la chiave API della tua applicazione. Questa chiave identifica la tua applicazione ai fini della gestione delle quote. 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 tutti i campi sono facoltativi, se non diversamente indicato:

Campo Tipo JSON Descrizione Note
homeMobileCountryCode number (uint32) Il Mobile Country Code (MCC) della rete di casa del dispositivo. Supportato per radioType gsm (predefinito), wcdma, lte e nr; non utilizzato per cdma.
Intervallo valido: 0-999.
homeMobileNetworkCode number (uint32) Il Mobile Network Code della 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-32.767.
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 radio è noto al client.
Se il campo viene omesso, l'API Geolocation utilizza per impostazione predefinita gsm, che genererà risultati non validi o nulli se il tipo di radio presunto non è corretto.
carrier string Il nome del corriere.
considerIp boolean Specifica se eseguire il fallback alla geolocalizzazione IP se i segnali Wi-Fi e delle torri cellulari sono mancanti, 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 torre cellulare. 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 della richiesta dell'API Geolocation.

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

Oggetti torre cellulare

L'array cellTowers del corpo della richiesta contiene zero o più oggetti torre 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 di seguito, che elenca anche gli intervalli di valori validi per ogni tipo di radio.
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 validi per il campo.
locationAreaCode number (uint32) Il Location Area Code (LAC) per le reti GSM e WCDMA.
L'ID di 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 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 (MCC) della torre cellulare. Obbligatorio per radioType gsm (predefinito), wcdma, lte e nr; non utilizzato per cdma.
Intervallo valido: 0-999.
mobileNetworkCode number (uint32) Il Mobile Network Code 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 i valori sono disponibili.

Campo Tipo JSON Descrizione Note
age number (uint32) Il numero di millisecondi trascorsi da quando questa cella era principale. Se l'età è 0, cellId o newRadioCellId rappresenta una misurazione corrente.
signalStrength number (double) Intensità del segnale radio misurata in dBm.
timingAdvance number (double) Il valore di timing advance.

Calcolo di cellId

I tipi di radio precedenti a NR (5G) utilizzano il campo cellId a 32 bit per passare 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-65.535.
  • 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'identificatore di cella UTRAN/GERAN (UC-ID), che è un valore intero a 28 bit che concatena l'identificatore del controller di rete radio (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 dell'ID cella a 16 bit nelle reti WCDMA, i risultati saranno errati o nulli.
  • Le reti LTE (4G) utilizzano l'identità della cella E-UTRAN (ECI), che è un valore intero a 28 bit che concatena l'identificatore del nodo B E-UTRAN (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 dell'ID cella a 8 bit nelle reti LTE, i risultati saranno errati o nulli.

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

Di seguito è riportato un esempio di oggetto torre cellulare LTE, che fa parte del corpo della richiesta.

{
  ...

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

La risposta alla richiesta precedente è simile alla seguente:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Calcolo di newRadioCellId

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 di rete all'API Geolocation.

  • Le reti NR (5G) utilizzano l'identità della cella New Radio (NCI) a 36 bit così com'è.
    Intervallo valido: 0-68719476735.

Di seguito è riportato un esempio di oggetto torre cellulare NR, che fa parte del corpo della richiesta.

{
  ...

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

La risposta alla richiesta precedente è simile alla seguente:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

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 dispositivi punto di accesso fissi fisicamente distinti. Il campo macAddress è obbligatorio. Tutti gli altri campi sono facoltativi. Il servizio ignora i punti di accesso che si spostano, ad esempio quelli su aerei e treni.

Campo Tipo JSON Descrizione Note
macAddress string L'indirizzo MAC del nodo Wi-Fi. In genere viene chiamato indirizzo BSS, BSSID o indirizzo MAC. Obbligatorio.Stringa esadecimale separata da due punti (:).
Solo gli indirizzi MAC amministrati universalmente possono essere individuati utilizzando l'API. Altri indirizzi MAC vengono ignorati automaticamente e potrebbero rendere una richiesta API effettivamente vuota. Per maggiori dettagli, consulta Eliminazione dei 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 dBm sono in genere -35 o inferiori e vanno da -128 a -10 dBm. Assicurati di includere il segno meno.
Per valori superiori a -10 dBm, l'API restituisce NOT FOUND.
age number (uint32) Il numero di millisecondi trascorsi dal rilevamento di questo access point.
channel number (uint32) Il canale su cui il client comunica con l'access point.
signalToNoiseRatio number (double) Il rapporto segnale/rumore attuale misurato in dB.

Di seguito è riportato un esempio di oggetto punto di accesso Wi-Fi, che fa parte del corpo della richiesta.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

La risposta alla richiesta precedente è simile alla seguente:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

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

La rimozione degli oggetti dei punti di accesso Wi-Fi con macAddress che sono un indirizzo di broadcast (FF:FF:FF:FF:FF:FF) o riservati dalla IANA può migliorare il tasso di successo delle chiamate API Geolocation che utilizzano il Wi-Fi come input. Se, dopo il filtro, è possibile determinare che una chiamata API Geolocation non andrebbe a buon fine, è possibile utilizzare misure di mitigazione come l'utilizzo di indicatori di posizione meno recenti o di punti di accesso Wi-Fi con indicatori più deboli. Questo approccio è un compromesso tra la necessità della tua 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 tu, in qualità di ingegnere dell'applicazione, potresti scegliere di applicare.

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 utilizzato per le funzioni di gestione della rete e multicast, il che ne preclude l'utilizzo come indicatore di posizione. Inoltre, devi rimuovere questi indirizzi MAC dagli input dell'API.

Ad esempio, gli indirizzi MAC utilizzabili per la geolocalizzazione possono essere raccolti da un array di stringhe macAddress denominate macs:

Java
String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
Python
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
JavaScript
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && m.substr(0, 8).toUpperCase() !== '00:00:5E');

L'utilizzo di questo filtro comporta che nell'elenco rimanga solo 1c:34:56:78:9a:bc. Poiché questo elenco contiene meno di 2 indirizzi MAC Wi-Fi, la richiesta non andrebbe a buon fine e verrebbe 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 campo secondario lat e un campo secondario lng.
  • accuracy: la precisione della posizione stimata, in metri. Rappresenta il raggio di un cerchio intorno alla location specificata.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

L'API restituisce una posizione e un raggio di precisione in base agli indicatori di input. Sebbene l'API possa restituire una posizione molto precisa, l'accuratezza può variare a seconda della sorgente, del numero, della densità e dell'intensità dei segnali disponibili. In genere, puoi aspettarti i seguenti raggi di precisione:

  • Punti di accesso Wi-Fi: se la richiesta include due o più wifiAccessPoints, il raggio di accuratezza restituito è in genere di circa 20 metri. La precisione migliora con il numero di punti di accesso e con segnali più forti (misurati in dBm), con intensità del segnale che in genere vanno da -100 a -20 dBm.
  • Torri cellulari: se le informazioni sul Wi-Fi non sono disponibili o sono insufficienti, l'API utilizza cellTowers per la posizione. La precisione varia in modo significativo in base al tipo di torre cellulare, all'intensità del segnale e alla densità della rete:
    • Le macro celle (il tipo più comune, utilizzato per la copertura di aree ampie) forniscono una precisione inferiore. Il raggio è in genere compreso tra centinaia di metri e diverse migliaia di metri nelle aree con una copertura di torri cellulari scarsa. Per le macrocelle, è raro ottenere un raggio di precisione inferiore a 100 metri. In genere, l'accuratezza è maggiore per le torri cellulari con segnali forti. I segnali forti sono in genere > -110 dBm per LTE (intervallo di segnale da -140 a -55 dBm), > -100 dBm per WCDMA (intervallo di segnale da -111 a -53 dBm), > -100 dBm per CDMA (intervallo di segnale da -120 a -40 dBm) e > -80 dBm per GSM (intervallo di segnale da -121 a -1 dBm).
    • Le small cell (ad es. femtocelle, picocelle o ripetitori interni) forniscono la posizione basata su celle più precisa, con raggi di precisione che possono essere compresi tra 10 e 30 metri.
  • Geolocalizzazione IP: se considerIp è true e non è possibile geolocalizzare i segnali Wi-Fi o delle torri cellulari, l'API stima la posizione in base all'indirizzo IP della richiesta. Questo metodo fornisce la precisione più bassa, con raggi che possono essere di migliaia di metri. Consulta la sezione Perché il raggio di precisione è molto ampio? nella guida alla risoluzione dei problemi.