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 eines key-Parameters angegeben wird. key ist der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für die Kontingentverwaltung. Weitere Informationen zum Abrufen eines Schlüssels

Anfragetext

Der Anforderungstext muss in JSON formatiert sein. Wenn der Anfragetext nicht enthalten ist, werden die Ergebnisse auf Grundlage der IP-Adresse des Standorts der Anfrage zurückgegeben. Die folgenden Felder werden unterstützt und alle Felder sind optional, sofern nicht anders angegeben:

Unten sehen Sie ein Beispiel für einen 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 einbezogen werden, 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.

• GSM-Netzwerke (2G) verwenden die 16-Bit-Cell ID (CID) in der vorliegenden Form. Gültiger Bereich: 0–65535.
• CDMA-Netzwerke (2G) verwenden die 16-Bit-Basisstations-ID (BID). Gültiger Bereich: 0–65535.
• WCDMA-Netzwerke (3G) verwenden die UTRAN/GERAN Cell Identity (UC-ID), ein ganzzahliger 28-Bit-Wert, der die 12-Bit-RNC-ID (Radio Network Controller Identifier) und die 16-Bit-Zellen-ID (CID) verkettet.
  Formel: rnc_id << 16 | cid.
  Gültiger Bereich: 0–268435455.
  Hinweis:Wenn Sie nur den 16-Bit-Cell-ID-Wert in WCDMA-Netzwerken angeben, führt dies zu falschen oder null Ergebnissen.
• LTE-Netzwerke (4G) verwenden die E-UTRAN Cell Identity (ECI). Dies ist ein ganzzahliger 28-Bit-Wert, der die 20-Bit-E-UTRAN Node B Identifier (eNBId) und die 8-Bit-Zellen-ID (CID) verkettet.
  Formel: enb_id << 8 | cid.
  Gültiger Bereich: 0–268435455.
  Hinweis:Wenn Sie nur den 8-Bit-Cell-ID-Wert in LTE-Netzwerken angeben, führt dies zu einem falschen Wert oder null.

Wenn in der API-Anfrage Werte außerhalb dieser Bereiche platziert werden, kann dies zu einem undefinierten Verhalten führen. Die API kann die Zahl nach Ermessen von Google kürzen, damit sie in den dokumentierten Bereich passt, eine Korrektur für 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 Array wifiAccessPoints des Anfragetexts muss mindestens zwei WLAN-Zugangspunktobjekte enthalten. macAddress ist erforderlich, alle anderen Felder sind optional.

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

{
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

Beispielanforderungen

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

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

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 vorangehenden MAC-Adressen sieht so aus:

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

Nicht verwendete WLAN-Zugangspunkte löschen

Das Entfernen von WiFi-Zugangspunktobjekten mit macAddresses, die lokal verwaltet werden, kann die Erfolgsrate von Geolocation API-Aufrufen verbessern, bei denen WLAN als Eingabe verwendet wird. Wenn nach dem Filtern festgestellt werden kann, dass ein Geolocation API-Aufruf nicht erfolgreich ist, können Abhilfemaßnahmen wie die Verwendung älterer Standortsignale oder WLAN-APs mit schwächeren Signalen verwendet werden. Dieser Ansatz stellt einen Kompromiss zwischen der Notwendigkeit einer Standortschätzung für Ihre Anwendung und den Anforderungen an Genauigkeit und Trefferquote dar. Die folgenden Filtertechniken zeigen, wie die Eingaben gefiltert werden. Es werden jedoch nicht die Abhilfemaßnahmen aufgeführt, die Sie als Application Engineer 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 bedeutendsten Byte der macAddress 0 ist, z.B. das 1-Bit, das durch 2 in 02:00:00:00:00:00 dargestellt wird. Die MAC-Adresse für die Übertragung (FF:FF:FF:FF:FF:FF) ist ein Beispiel für eine MAC-Adresse, die von diesem Filter sinnvoll ausgeschlossen werden kann.

Der Bereich der MAC-Adressen 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, sodass sie nicht als Standortsignal verwendet werden können. Sie sollten diese MAC-Adressen auch aus den Eingaben in die API entfernen.

Verwendbare MAC-Adressen für die Standortbestimmung können beispielsweise 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, verbleiben nur 1c:34:56:78:9a:bc in der Liste. Da diese Liste weniger als zwei WLAN-MAC-Adressen enthält, ist die Anfrage nicht erfolgreich und die HTTP 404-Antwort(notFound) wird zurückgegeben.

Geocoding-Antworten

Bei einer erfolgreichen Anfrage zur Standortbestimmung wird eine Antwort im JSON-Format zurückgegeben, in der ein Standort und ein Radius festgelegt sind.

• location: Die vom Nutzer geschätzten Breiten- und Längengrade 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 die angegebene location dar.

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