Questa pagina è stata tradotta dall'API Cloud Translation.

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. 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 è 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 specificato:

Campo	Tipo JSON	Descrizione	Note
`homeMobileCountryCode`	`number` (`uint32`)	Il codice paese del dispositivo mobile (Centro clienti) 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 codice di rete mobile della rete di casa del dispositivo. Questo è l'MNC per GSM, WCDMA, LTE e NR. Il CDMA utilizza l'ID di sistema (SID)	Intervallo valido per MNC: 0-999. Intervallo valido per il SID: 0-32767.
`radioType`	`string`	Il tipo di radio mobile. I valori supportati sono `gsm`, `cdma`, `wcdma`, `lte` e `nr`.	Anche se questo campo è facoltativo, deve essere sempre incluso se il tipo di radio è noto al client. Se il campo viene omesso, l'API Geolocation sarà impostata per impostazione predefinita su `gsm`, il che restituirà risultati non validi o pari a zero se il tipo di opzione presunto è errato.
`carrier`	`string`	Il nome dell'operatore.
`considerIp`	`boolean`	Consente di specificare se utilizzare la geolocalizzazione degli IP nel caso in cui i segnali Wi-Fi e del ripetitore di telefonia mobile non siano presenti, vuoti o non siano sufficienti per stimare la posizione del dispositivo.	Il valore predefinito è `true`. Imposta `considerIp` su `false` per evitare il fallback.
`cellTowers`	`array`	Una serie di oggetti di torri cellulari.	Consulta la sezione Oggetti delle torri cellulari di seguito.
`wifiAccessPoints`	`array`	Una serie di oggetti access point Wi-Fi.	Consulta la sezione Oggetti punti di accesso Wi-Fi di seguito.

Di seguito è mostrato 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 ciascun tipo di opzione di opzione.
`newRadioCellId`	`number` (`uint64`)	Identificatore univoco della cella NR (5G).	Obbligatorio per `radioType` `nr`; rifiutato per gli altri tipi. Consulta la sezione Calcolo di newRadioCellId di seguito, che riporta anche l'intervallo di valori valido per il campo.
`locationAreaCode`	`number` (`uint32`)	Il codice LAC (Location Area Code) per le reti GSM e WCDMA. L'ID rete (NID) per le reti CDMA. Il codice dell'area di monitoraggio (TAC) per le reti LTE e NR.	Obbligatorio per `radioType` `gsm` (valore 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 (CPC) 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 del ripetitore di telefonia mobile. Si tratta dell'MNC per GSM, WCDMA, LTE e NR. Il CDMA utilizza l'ID di sistema (SID).	Obbligatorio. Intervallo valido per MNC: 0-999. Intervallo valido per il 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 da quando questa cella era 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 del tempo.

Calcolo di `cellId` in corso...

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 il Cell ID (CID) a 16 bit così com'è. Intervallo valido: 0-65535.
Le reti CDMA (2G) utilizzano l'ID della stazione di base a 16 bit (bid) così com'è. Intervallo valido: 0-65535.
Le reti WCDMA (3G) utilizzano UTRAN/GERAN Cell Identity (UC-ID), che è un valore intero a 28 bit che concatena l'RNC-ID (Radio Network Controller Identifier) a 12 bit e l'ID cella a 16 bit (CID).
Formula: rnc_id << 16 | cid.
Intervallo valido: 0-268435455.
Nota:se specifichi solo il valore Cell ID a 16 bit nelle reti WCDMA, i risultati non saranno corretti o non ne riceverai nessuno.
Le reti LTE (4G) utilizzano E-UTRAN Cell Identity (ECI), un valore intero a 28 bit che concatena l'identificatore E-UTRAN Node B a 20 bit (eNBId) e l'ID cella a 8 bit (CID).
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 non saranno corretti o non verranno restituiti risultati.

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

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

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

Di seguito è riportato un esempio di oggetto della 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. macAddress è obbligatorio; tutti gli altri campi sono facoltativi.

Campo	Tipo JSON	Descrizione	Note
`macAddress`	`string`	L'indirizzo MAC del nodo Wi-Fi. Si tratta in genere di indirizzo BSS, BSSID o MAC.	Obbligatorio. Stringa esadecimale separata da due punti (`:`). Tramite l'API è possibile trovare solo gli indirizzi MAC amministrati universalmente. Altri indirizzi MAC vengono ignorati automaticamente e possono portare a una richiesta API vuota. Per maggiori dettagli, consulta la sezione Abbandono di 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 generalmente compresi tra -35 e -35 dBm e sono compresi tra -128 e -10 dBm. Accertati 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 cliente comunica con il punto di accesso.
`signalToNoiseRatio`	`number` (`double`)	Il rapporto tra segnale attuale e rumore misurato in dB.

Di seguito è mostrato un esempio di oggetto punto di accesso Wi-Fi.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "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": "94:b4:0f:fd:c1:40",
      "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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

Eliminazione dei punti di accesso Wi-Fi non utilizzati

La rimozione di oggetti dei punti 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 dei filtri, è possibile determinare che una chiamata all'API Geolocation non ha esito positivo, è possibile utilizzare misure di mitigazione come l'utilizzo di segnali di posizione meno recenti o di AP Wi-Fi con segnali più deboli. Questo approccio rappresenta un compromesso tra l'esigenza della tua applicazione di stima della località 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 automaticamente eliminati 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 1 bit rappresentato da 2 in 02:00:00:00:00:00. L'indirizzo MAC di broadcast (FF:FF:FF:FF:FF:FF) è un esempio di indirizzo MAC che sarebbe utilmente escluso da questo filtro.

L'intervallo di indirizzi MAC tra 00:00:5E:00:00:00 e 00:00:5E:FF:FF:FF è riservato a IANA e spesso viene utilizzato per la gestione della rete e le funzioni multicast che ne impediscono l'uso come segnale di località. Devi anche rimuovere questi indirizzi 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');

Se utilizzi questo filtro, nell'elenco rimangono 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 località e un raggio.

location: coordinate di latitudine e longitudine stimate dell'utente, in gradi. Contiene un lat e un sottocampo lng.
accuracy: precisione della posizione stimata in metri. Rappresenta il raggio di un cerchio intorno all'elemento location specificato.

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