Richiesta di risposta e geolocalizzazione

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 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 sono tutti facoltativi, se non diversamente indicato:

Campo Tipo JSON Descrizione Note
homeMobileCountryCode number (uint32) Il codice paese mobile (MCC) 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 rete mobile per la rete di casa del dispositivo. Si tratta dell'MNC per GSM, WCDMA, LTE e NR.
CDMA utilizza l'ID sistema (SID)
Intervallo valido per MNC: 0-999.
Intervallo valido per l'ID cliente: 0-32767.
radioType string Il tipo di 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 è conosciuto dal cliente.
Se il campo viene omesso, l'API Geolocation imposta per impostazione predefinita gsm, il che porterà a risultati non validi o nulli se il tipo di radio presunto è sbagliato.
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 Un array di oggetti torre di telefonia mobile. Consulta la sezione Oggetti torre di telefonia mobile 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": "gsm",
  "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 di telefonia 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 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 codice area geografica (LAC) per le reti GSM e WCDMA.
L'ID rete (NID) per le reti CDMA.
Il codice area di monitoraggio (TAC) per le reti LTE e NR.
Obbligatorio per radioType gsm (valore predefinito) e cdma, facoltativo per altri valori.
Estensione valida con gsm, cdma, wcdma e lte: 0-65535.
Esempio di 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 codice di rete mobile della torre cellulare. Si tratta dell'MNC per GSM, WCDMA, LTE e NR.
CDMA utilizza l'ID sistema (SID).
Obbligatorio.
Estensione valida per MNC: 0-999.
Intervallo valido per l'ID cliente: 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'ultima volta che 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 anticipo sui tempi.

Calcolo di cellId

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à di cella UTRAN/GERAN (UC-ID), che è un valore intero di 28 bit che concatena l'identificatore del controller di rete radio (RNC-ID) di 12 bit e l'ID cella (CID) di 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 pari a zero.
  • Le reti LTE (4G) utilizzano l'identità della cella E-UTRAN (ECI), che è un valore intero di 28 bit concatenando l'identificatore del nodo B E-UTRAN (eNBId) di 20 bit e l'ID cella (CID) di 8 bit.
    Formula: enb_id << 8 | cid.
    Intervallo valido: 0-268435455.
    Nota: se specifichi solo il valore dell'ID cella di 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 può comportare un comportamento non definito. L'API, a discrezione di Google, può troncare il numero in modo che rientri nell'intervallo documentato, dedurre una correzione del radioType o restituire un risultato NOT_FOUND senza alcun 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 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 torre di telefonia mobile 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 che rappresentano dispositivi punto di accesso fisicamente distinti. 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 indirizzi MAC gestiti universalmente possono essere individuati tramite l'API. Gli altri indirizzi MAC vengono ignorati e potrebbero causare l'eliminazione di una richiesta API. 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 in 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 dal rilevamento di questo punto di accesso.
channel number (uint32) Il canale tramite il quale 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
}

Rimuovere i punti di accesso Wi-Fi inutilizzati

La rimozione di oggetti punto di accesso Wi-Fi con macAddress amministrati localmente può migliorare il tasso di successo delle chiamate all'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. 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 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 bit 1 rappresentato da 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 compreso 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 di multicast, il che preclude il loro utilizzo come indicatore di posizione. Devi anche rimuovere questi indirizzo 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:

Java
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")));
    
Python
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')]
    
JavaScript
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, la richiesta non andrà a buon fine e verrà restituita una risposta HTTP 404 (notFound).

Risposte di geolocalizzazione

Una richiesta di geolocalizzazione riuscita restituisce una risposta in formato JSON che definisce una posizione e un raggio.

  • location: le coordinate di latitudine e longitudine stimate dell'utente in gradi. Contiene un sottocampo lat e un sottocampo lng.
  • accuracy: la precisione della posizione stimata, in metri. Rappresenta il raggio di un cerchio intorno al dato location.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}