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. Un key è il chiave API. Questa chiave identifica l'applicazione ai fini della quota gestione dei dispositivi. 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) per la rete di casa del dispositivo.	Supportato per `radioType` `gsm` (impostazione predefinita), `wcdma`, `lte` e `nr`; non utilizzato per `cdma`. Intervallo valido: 0-999.
`homeMobileNetworkCode`	`number` (`uint32`)	Il codice di rete mobile per la rete di casa del dispositivo. Questa è l'MNC per GSM, WCDMA, LTE e NR. Il CDMA utilizza l'ID sistema (SID)	Intervallo valido per MNC: 0-999. Intervallo valido per SID: 0-32767.
`radioType`	`string`	Il tipo di segnale radio mobile. I valori supportati sono `gsm`, `cdma`, `wcdma`, `lte` e `nr`.	Questo campo è facoltativo, ma deve essere sempre incluso se il tipo di opzione radio è noti al cliente. Se il campo viene omesso, l'API Geolocation sarà `gsm` per impostazione predefinita, che genera risultati non validi o pari a zero se il presunto tipo di segnale radio è risposta errata.
`carrier`	`string`	Il nome dell'operatore.
`considerIp`	`boolean`	Specifica se ricorrere alla geolocalizzazione IP se mancano i segnali del Wi-Fi e delle torri cellulari. vuoto o non sufficiente per stimare la posizione del dispositivo.	Il valore predefinito è `true`. Imposta `considerIp` su `false` per evitare i fallback.
`cellTowers`	`array`	Una serie di oggetti delle torri cellulari.	Consulta la sezione Oggetti delle torri cellulari di seguito.
`wifiAccessPoints`	`array`	Una serie di oggetti del 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 delle torri cellulari

L'array cellTowers del corpo della richiesta contiene zero o più di oggetti contenenti una 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 riportata di seguito, che elenca anche gli intervalli di valori validi per ogni tipo di opzione.
`newRadioCellId`	`number` (`uint64`)	Identificatore univoco della cella NR (5G).	Obbligatorio per `radioType` `nr`; rifiutato per altri di testo. Consulta la sezione Calcolo di newRadioCellId riportata di seguito. che elenca anche l'intervallo di valori valido per il campo.
`locationAreaCode`	`number` (`uint32`)	Il prefisso di località (LAC) per le reti GSM e WCDMA. L'ID rete (NID) delle reti CDMA. Il codice dell'area di monitoraggio (TAC) per le reti LTE e NR.	Obbligatorio per `radioType` `gsm` (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 (Centro clienti) 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. Questa è l'MNC per GSM, WCDMA, LTE e NR. Il CDMA utilizza l'ID sistema (SID).	Obbligatorio. Intervallo valido per MNC: 0-999. Intervallo valido per SID: 0-32767.

I seguenti campi facoltativi non sono 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 è primaria.	Se l'età è 0, `cellId` o `newRadioCellId` rappresenta un valore attuale misurazione.
`signalStrength`	`number` (`double`)	Intensità del segnale radio misurata in dBm.
`timingAdvance`	`number` (`double`)	La in anticipo valore.

Calcolo di `cellId` in corso...

I tipi di segnali radio precedenti a NR (5G) utilizzano il campo cellId a 32 bit per trasmettere la rete l'ID cella all'API Geolocation.

Le reti GSM (2G) utilizzano l'ID cella a 16 bit così com'è. Intervallo valido: 0-65535.
Le reti CDMA (2G) utilizzano l'ID stazione base a 16 bit (BID) così com'è. Intervallo valido: 0-65535.
Le reti WCDMA (3G) utilizzano l'identità cellulare UTRAN/GERAN (UC-ID), che è un numero intero a 28 bit concatenando il Radio Network Controller Identifier (RNC-ID) a 12-bit e l'identificatore di rete ID cella (CID).
Formula: rnc_id << 16 | cid.
Intervallo valido: 0-268435455.
Nota: se specifichi solo il valore ID cella a 16 bit nelle reti WCDMA, non è corretto o non genera alcun risultato.
Le reti LTE (4G) utilizzano E-UTRAN Cell Identity (ECI), che è un valore intero a 28 bit concatenando l'identificatore B del nodo E-UTRAN a 20 bit (eNBId) e l'ID della 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, non è corretto o non genera alcun risultato.

L'inserimento di valori al di fuori di questi intervalli nella richiesta API potrebbe causare un comportamento indefinito. L'API, a discrezione di Google, può troncare il numero in modo che rientri nell'intervallo documentato, dedurre una correzione a radioType o restituisci un risultato NOT_FOUND senza indicatore nella risposta.

Di seguito è riportato un esempio di oggetto di un ripetitore di telefonia mobile 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 di cella sono più lunghi di 32 bit, utilizzano Campo newRadioCellId per trasmettere l'ID cella di rete a API Geolocation.

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

Di seguito è riportato un esempio di oggetto NR di colonne.

{
  "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; tutto gli altri campi sono facoltativi.

Campo	Tipo JSON	Descrizione	Note
`macAddress`	`string`	L'indirizzo MAC del nodo Wi-Fi. In genere è chiamato indirizzo BSS, BSSID o MAC.	Obbligatorio.Stringa esadecimale separata da due punti (`:`). Solo amministrato universalmente Gli indirizzi MAC possono essere individuati tramite l'API. Altri indirizzi MAC sono eliminati automaticamente e può far sì che una richiesta API diventi efficace vuoto. Per maggiori dettagli, consulta l'articolo sull'interruzione dell'accesso Wi-Fi inutile. punti di accesso.
`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.
`age`	`number` (`uint32`)	Il numero di millisecondi da quando è stato rilevato questo punto di accesso.
`channel`	`number` (`uint32`)	Il canale su cui il client comunica con il punto di accesso.
`signalToNoiseRatio`	`number` (`double`)	L'attuale rapporto tra segnale e rumore misurate 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 esempi 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
    }
  ]
}

Dopodiché potrai utilizzare cURL per per effettuare una 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

Rimozione degli oggetti del punto di accesso Wi-Fi con macAddress che sono amministrata localmente può migliorare la percentuale di successo delle chiamate API Geolocation che utilizzano il Wi-Fi come input. Se, dopo l'applicazione di filtri, si può stabilire che la chiamata all'API Geolocation non riescono, mitigazioni come l'utilizzo di indicatori di posizione obsoleti o punti di accesso Wi-Fi con è possibile usare segnali più deboli. Si tratta di un compromesso tra necessità dell'applicazione di una stima della posizione, oltre alla sua precisione e richiamo i tuoi requisiti. Le seguenti tecniche di filtro mostrano come applicare un filtro gli input, ma non mostrare le mitigazioni che potresti, come l'applicazione ingegnere, scegliere di fare domanda.

Gli indirizzi MAC amministrati localmente non sono indicatori di posizione utili per il API e vengono eliminati automaticamente dalle richieste. Puoi rimuovere questi indirizzi MAC garantendo che la seconda parte meno significativa Il byte più significativo di macAddress è 0, ad esempio il 1 bit 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 utilmente escluse da questo filtro.

L'intervallo di indirizzi MAC tra 00:00:5E:00:00:00 e 00:00:5E:FF:FF:FF sono prenotato per IANA e spesso utilizzata per la gestione della rete e le funzioni multicast che ne precludono l'uso come segnale di posizione. Dovresti rimuovere anche questi gli indirizzi MAC dagli input all'API.

Ad esempio, gli indirizzi MAC utilizzabili per la geolocalizzazione possono essere raccolti da un array di macAddress stringhe 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'uso di questo filtro determina solo 1c:34:56:78:9a:bc rimanenti nell'elenco. Poiché questo elenco contiene meno di 2 indirizzi MAC Wi-Fi, il non riesce e viene visualizzato un errore HTTP 404 (notFound) di Google Cloud.

Risposte di geolocalizzazione

Una richiesta di geolocalizzazione riuscita restituisce una risposta in formato JSON. definire una località e un raggio.

location: latitudine e longitudine stimate dell'utente coordinate, in gradi. Contiene un lat e un lng .
accuracy: la precisione della posizione stimata, in metri. Rappresenta il raggio di un cerchio intorno a una data location.

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