Anfrage und Antwort zur Standortbestimmung

Geolocation-Anforderungen

Geolocation-Anforderungen werden mit POST an die folgende URL gesendet:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

Sie müssen in Ihrer Anfrage einen Schlüssel angeben, der als Wert des Parameters key enthalten ist. key ist der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung zum Zweck der Kontingentverwaltung. Weitere Informationen zum Abrufen eines Schlüssels

Anfragetext

Der Anforderungstext muss in JSON formatiert sein. Ohne Angabe des Anfragetexts werden die Ergebnisse auf Grundlage der IP-Adresse des Anfragestandorts zurückgegeben. Sofern nicht anders angegeben, werden die folgenden Felder unterstützt und alle Felder sind optional:

Unten sehen Sie ein Beispiel für eine Geolocation API-Anfragetext.

{
  "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.
  ]
}

Mobilfunkmastobjekte

Das Array cellTowers des Anfragetexts enthält null oder mehr Mobilfunkmastobjekte.

Die folgenden optionalen Felder werden nicht verwendet, können aber enthalten sein, wenn Werte verfügbar sind.

cellId wird berechnet

Funktypen vor NR (5G) verwenden das 32-Bit-Feld cellId, um die Netzwerkzellen-ID an die Geolocation API zu übergeben.

• In GSM-Netzwerken (2G) wird die 16-Bit-Zellen-ID (CID) verwendet. Gültiger Bereich: 0–65535.
• In CDMA-Netzwerken (2G) wird die 16-Bit-Basisstations-ID (bid) in der vorliegenden Form verwendet. Gültiger Bereich: 0–65535.
• WCDMA-Netzwerke (3G) verwenden die UTRAN/GERAN Cell Identity (UC-ID), eine 28-Bit-Ganzzahl, die den 12-Bit-Radio Network Controller Identifier (RNC-ID) und die 16-Bit-Cell-ID (CID) verkettet.
  Formel: rnc_id << 16 | cid.
  Gültiger Bereich: 0–268435455
  Hinweis:Wenn Sie in WCDMA-Netzwerken nur den 16-Bit-Zellen-ID-Wert angeben, werden falsche oder null Ergebnisse ausgegeben.
• LTE-Netzwerke (4G) verwenden die E-UTRAN Cell Identity (ECI), eine 28-Bit-Ganzzahl, die den 20-Bit-E-UTRAN-Knoten-B-Identifikator (eNBId) und die 8-Bit-Cell-ID (CID) verkettet.
  Formel: enb_id << 8 | cid.
  Gültiger Bereich: 0–268435455
  Hinweis:Wenn Sie in LTE-Netzwerken nur den 8-Bit-Zellen-ID-Wert angeben, werden falsche oder null Ergebnisse ausgegeben.

Wenn Werte außerhalb dieser Bereiche in der API-Anfrage platziert werden, kann das zu einem nicht definierten Verhalten führen. Die API kann die Zahl nach Ermessen von Google kürzen, damit sie in den dokumentierten Bereich passt, kann eine Korrektur an radioType ableiten oder ein NOT_FOUND-Ergebnis ohne Indikator in der Antwort zurückgeben.

Unten sehen Sie ein Beispiel für ein LTE-Mobilfunkmastobjekt.

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

newRadioCellId wird berechnet

Neuere Netzwerke, deren Zellen-IDs länger als 32 Bit sind, verwenden das 64-Bit-Feld newRadioCellId, um die Netzwerkzellen-ID an die Geolocation API zu übergeben.

• NR-Netzwerke (5G) verwenden in der vorliegenden Form die 36-Bit-New Radio Cell Identity (NCI).
  Gültiger Bereich: 0–68719476735.

Unten sehen Sie ein Beispiel für ein NR-Mobilfunkmastobjekt.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

WiFi-Zugriffspunktobjekte

Das wifiAccessPoints-Array des Anfragetextes muss mindestens zwei WLAN-Zugangspunkt-Objekte enthalten. macAddress ist ein Pflichtfeld. Alle anderen Felder sind optional.

Im Folgenden finden Sie ein Beispiel für ein WiFi-Zugriffspunktobjekt.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Beispielanforderungen

Wenn Sie die Geolocation API mit Beispieldaten ausprobieren möchten, speichern Sie die folgende JSON-Datei in einer Datei:

{
  "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
    }
  ]
}

Sie können dann cURL verwenden, um Ihre Anfrage über die Befehlszeile zu stellen:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

Die Antwort für die vorherigen MAC-Adressen sieht so aus:

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

Nicht verwendete WLAN-Zugangspunkte verwerfen

Durch das Entfernen von Wifi-Zugangspunkt-Objekten mit macAddress-Objekten, die lokal verwaltet werden, kann die Erfolgsquote von Geolocation API-Aufrufen verbessert werden, die WLAN als Eingabe verwenden. Sollte sich nach dem Filtern feststellen, dass ein Geolocation API-Aufruf nicht erfolgreich ist, können Abhilfemaßnahmen wie die Verwendung älterer Standortsignale oder WLAN-APs mit schwächeren Signalen ergriffen werden. Dieser Ansatz stellt einen Kompromiss zwischen der Notwendigkeit einer Standortschätzung und den Anforderungen an Precision und Recall dar. Die folgenden Filtertechniken zeigen, wie Sie die Eingaben filtern. Sie sehen jedoch nicht, welche Schutzmaßnahmen Sie als Anwendungsentwickler anwenden können.

Lokal verwaltete MAC-Adressen sind keine nützlichen Standortsignale für die API und werden ohne Meldung aus Anfragen entfernt. Sie können solche MAC-Adressen entfernen, indem Sie dafür sorgen, dass das zweitniedrigste Bit des wichtigsten Byte des macAddress-Bytes 0 ist, z.B. das 1-Bit, das durch 2 in 02:00:00:00:00:00 dargestellt wird. Die Broadcast-MAC-Adresse (FF:FF:FF:FF:FF:FF) ist ein Beispiel für eine MAC-Adresse, die durch diesen Filter sinnvoll ausgeschlossen werden kann.

Der MAC-Adressbereich zwischen 00:00:5E:00:00:00 und 00:00:5E:FF:FF:FF ist für IANA reserviert und wird häufig für die Netzwerkverwaltung und Multicast-Funktionen verwendet, die ihre Verwendung als Standortsignal ausschließen. Sie sollten diese MAC-Adressen auch aus Eingaben in die API entfernen.

Zum Beispiel können nutzbare MAC-Adressen für die Standortbestimmung aus einem Array von macAddress-Strings mit dem Namen macs ermittelt werden:

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

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

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

Wenn Sie diesen Filter verwenden, verbleibt nur 1c:34:56:78:9a:bc in der Liste. Da diese Liste weniger als 2 WLAN-MAC-Adressen enthält, wäre die Anfrage nicht erfolgreich und eine HTTP 404-(notFound)-Antwort wird zurückgegeben.

Geocoding-Antworten

Eine erfolgreiche Anfrage zur Standortbestimmung gibt eine Antwort im JSON-Format zurück, die einen Standort und einen Radius definiert.

• location: die geschätzten Breiten- und Längengrade des Nutzers in Grad Enthält ein lat- und ein lng-Unterfeld.
• accuracy: die Genauigkeit des geschätzten Standorts in Metern. Dies stellt den Radius eines Kreises um den angegebenen location dar.

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