Questa pagina è stata tradotta dall'API Cloud Translation.

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. 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. Sono supportati i seguenti campi e tutti sono facoltativi, se non diversamente indicato:

Campo	Tipo JSON	Descrizione	Note
`homeMobileCountryCode`	`number` (`uint32`)	Il codice paese mobile (MCC) della rete di origine del dispositivo.	Supportato per `radioType` `gsm` (valore 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-32767.
`radioType`	`string`	Il tipo di radio mobile. I valori supportati sono `gsm`, `cdma`, `wcdma`, `lte` e `nr`.	Sebbene questo campo sia facoltativo, deve sempre essere incluso se il tipo di radio è noto al client. Se il campo viene omesso, l'API Geolocation utilizza per impostazione predefinita `gsm`, il che comporterà risultati non validi o pari a zero se il tipo di radio presunto è errato.
`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": "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 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 locale (LAC) per le reti GSM e WCDMA. L'ID rete (NID) per le reti CDMA. Il codice di area di monitoraggio (TAC) per le reti LTE e NR.	Obbligatorio per `radioType` `gsm` (impostazione predefinita) 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 codice paese mobile (Mobile Country Code, MCC) 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 è diventata primaria.	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 dell'anticipo della tempistica.

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), 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 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:la specifica del solo valore ID cella a 8 bit nelle reti LTE comporta risultati errati o pari a zero.

L'inserimento di valori al di fuori di questi intervalli nella richiesta API potrebbe comportare un comportamento indefinito. L'API, a discrezione di Google, può 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.

{
  "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 a 64 bit per trasmettere 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.

{
  "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 viene chiamato BSS, BSSID o indirizzo MAC.	Obbligatorio.Stringa esadecimale separata da due punti (`:`). Solo gli indirizzi MAC gestiti universalmente possono essere individuati tramite l'API. Gli altri indirizzi MAC vengono eliminati automaticamente e potrebbero rendere una richiesta API effettivamente vuota. Per maggiori dettagli, vedi 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 pari o inferiori a -35 e vanno da -128 a -10 dBm. Assicurati di includere il segno meno. Per i valori superiori a -10 dBm, l'API restituisce `NOT FOUND`.
`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`)	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 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 non utilizzati

La rimozione di oggetti punto di accesso Wi-Fi con macAddress che sono amministrati localmente può migliorare il tasso di successo delle chiamate dell'API Geolocation che utilizzano il Wi-Fi come input. Se, dopo il filtraggio, si può determinare che una chiamata all'API di geolocalizzazione non andrà a buon fine, è possibile utilizzare misure di mitigazione come l'utilizzo di segnali di localizzazione precedenti o AP Wi-Fi con segnali più deboli. Questo approccio rappresenta 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 mitigazioni che potresti scegliere di applicare in qualità di ingegnere delle applicazioni.

Gli indirizzi MAC gestiti localmente non sono indicatori di posizione utili per l'API e vengono eliminati 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 sarebbe escluso in modo utile da questo filtro.

L'intervallo di indirizzi MAC compreso tra 00:00:5E:00:00:00 e 00:00:5E:FF:FF:FF è riservato all'IANA e spesso utilizzato per la gestione della rete e le funzioni di multicast che ne impediscono l'utilizzo come segnale di localizzazione. Devi anche 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 denominato 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'utilizzo di questo filtro comporta la visualizzazione di solo 1c:34:56:78:9a:bc nell'elenco. Poiché questo elenco contiene meno di due 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 campo secondario lat e un campo secondario lng.
accuracy: la precisione della posizione stimata, in metri. Rappresenta il raggio di un cerchio intorno al location specificato.

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