Richiesta di risposta e geolocalizzazione

Richieste di localizzazione

Le richieste di localizzazione 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 key parametro. Un key è la chiave API della tua applicazione. Questa chiave identifica la tua applicazione ai fini della gestione delle quote management. 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. Sono supportati i seguenti campi, tutti facoltativi, se non diversamente indicato:

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.

I seguenti campi facoltativi non vengono utilizzati, ma possono essere inclusi se sono disponibili valori.

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-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à cella UTRAN/GERAN (UC-ID), che è un valore intero a 28 bit che concatena l'identificatore 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 pari a zero.
• Le reti LTE (4G) utilizzano l'identità cella E-UTRAN (ECI), che è un valore intero a 28 bit che concatena l'identificatore 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 pari a zero.

L'inserimento di valori al di fuori di questi intervalli nella richiesta API può comportare un comportamento indefinito. L'API, a discrezione di Google, può troncare il numero in modo che rientri nell'intervallo documentato, dedurre una correzione di 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 a 64 bit newRadioCellId per passare l'ID cella di rete all' API Geolocation.

• Le reti NR (5G) utilizzano l'identità 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 WiFi

L'array wifiAccessPoints del corpo della richiesta deve contenere due o più oggetti punto di accesso WiFi 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.

Di seguito è riportato un esempio di oggetto punto di accesso WiFi, che fa parte del corpo della richiesta, è mostrato.

{
  ...
  
  "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 agli indirizzi MAC precedenti è simile alla seguente:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Eliminazione dei punti di accesso WiFi inutilizzati

La rimozione degli oggetti punto di accesso WiFi con macAddress che sono un indirizzo di trasmissione (FF:FF:FF:FF:FF:FF) o riservati dall' IANA può migliorare la percentuale di successo delle chiamate all'API Geolocation che utilizzano il WiFi come input. Se, dopo il filtraggio, è possibile determinare che una chiamata all'API Geolocation non andrà a buon fine, è possibile utilizzare misure di mitigazione come l'utilizzo di segnali di localizzazione precedenti o di punti di accesso WiFi con segnali più deboli. Questo approccio è un compromesso tra la necessità della tua applicazione di una stima della posizione e i requisiti di precisione e richiamo. Le seguenti tecniche di filtraggio mostrano come filtrare gli input, ma non mostrano le misure di mitigazione che potresti scegliere di applicare come ingegnere dell'applicazione.

L'intervallo di indirizzi MAC compreso tra 00:00:5E:00:00:00 e 00:00:5E:FF:FF:FF è riservato all'IANA e viene spesso utilizzato per le funzioni di gestione della rete e multicast, impedendone l'utilizzo come segnale di localizzazione. Dovresti anche rimuovere questi indirizzi MAC dagli input dell'API.

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

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")));
    

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')]
    

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 la permanenza di solo 1c:34:56:78:9a:bc nell'elenco. Poiché questo elenco contiene meno di due indirizzi MAC WiFi, la richiesta non andrà a buon fine e verrà restituita una risposta HTTP 404 (notFound) risposta.

Risposte di localizzazione

Una richiesta di localizzazione 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 attorno al dato location.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

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

• Punti di accesso WiFi: se la richiesta include due o più wifiAccessPoints, il raggio di precisione restituito è in genere di circa 20 metri. La precisione migliora con il numero di punti di accesso e segnali più intensi (misurati in dBm), con intensità del segnale che in genere vanno da -100 a -20 dBm.
• Ripetitori di telefonia mobile: se le informazioni WiFi 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 estese ) forniscono una precisione inferiore. Il raggio è in genere compreso tra centinaia di metri e può arrivare a diverse migliaia di metri nelle aree con una copertura delle torri cellulari scarsa. Per le macro celle, è raro ottenere un raggio di precisione inferiore a 100 metri. La precisione è in genere maggiore per i ripetitori di telefonia mobile con segnali intensi. I segnali intensi 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 celle piccole (ad es. femtocelle, picocelle o ripetitori indoor) forniscono la posizione più precisa basata sulle celle, con raggi di precisione che possono essere compresi tra 10 e 30 metri.
• Localizzazione IP: se considerIp è true e non è possibile localizzare i segnali WiFi 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 grande? nella guida alla risoluzione dei problemi.