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 enthalten ist. Ein key ist der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung zur 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 basierend auf der IP-Adresse des Anfragestandorts zurückgegeben. Die folgenden Felder werden unterstützt. Sofern nicht anders angegeben, sind alle Felder optional:

Unten finden 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 cellTowers-Array im Anfragetext enthält null oder mehr Mobilfunkmastenobjekte.

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

Berechnung von cellId

Bei Funktypen vor NR (5G) wird das 32‑Bit-Feld cellId verwendet, um die Zell-ID des Mobilfunknetzes an die Geolocation API zu übergeben.

• GSM-Netzwerke (2G) verwenden die 16-Bit-Zellen-ID (Cell ID, CID) unverändert. Gültiger Bereich: 0–65535.
• CDMA-Netzwerke (2G) verwenden die 16-Bit-Basisstations-ID (BID) unverändert. Gültiger Bereich: 0–65535.
• In WCDMA-Netzwerken (3G) wird die UTRAN/GERAN-Zellen-ID (UC-ID) verwendet. Dies ist ein 28-Bit-Ganzzahlwert, der die 12-Bit-Radio Network Controller Identifier (RNC-ID) und die 16-Bit-Zellen-ID (Cell ID, CID) zusammenfasst.
  Formel: rnc_id << 16 | cid.
  Gültiger Bereich: 0–268435455.
  Hinweis:Wenn Sie in WCDMA-Netzwerken nur den 16-Bit-Wert der Zellen-ID angeben, erhalten Sie falsche oder null Ergebnisse.
• LTE-Netzwerke (4G) verwenden die E-UTRAN-Zellen-ID (ECI), einen 28-Bit-Ganzzahlwert, der die 20-Bit-E-UTRAN-Knoten-B-Kennung (eNBId) und die 8-Bit-Zellen-ID (CID) zusammenfasst.
  Formel: enb_id << 8 | cid.
  Gültiger Bereich: 0–268435455.
  Hinweis:Wenn Sie in LTE-Netzwerken nur den 8‑Bit-Wert der Zellen-ID angeben, erhalten Sie falsche Ergebnisse oder keine Ergebnisse.

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

Unten finden Sie ein Beispiel für ein LTE-Mobilfunkmastenobjekt.

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

Berechnung newRadioCellId

In neueren Netzwerken, deren Zell-IDs länger als 32 Bit sind, wird das 64-Bit-newRadioCellId-Feld verwendet, um die Zell-ID des Netzwerks an die Geolocation API zu übergeben.

• In NR-Netzwerken (5G) wird die 36-Bit-New Radio Cell Identity (NCI) unverändert verwendet.
  Gültiger Bereich: 0–68719476735.

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

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

WiFi-Zugriffspunktobjekte

Das wifiAccessPoints-Array im Anfragetext muss mindestens zwei WLAN-Zugangspunktobjekte enthalten, die physisch getrennte Zugangspunktgeräte darstellen. macAddress ist ein Pflichtfeld, 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 die folgende JSON-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 die 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.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Nicht verwendete WLAN-Zugangspunkte entfernen

Wenn Sie WLAN-Zugangspunktobjekte mit macAddresss entfernen, die lokal verwaltet werden, kann sich 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 wäre, können Maßnahmen wie die Verwendung älterer Standortsignale oder WLAN-Zugangspunkte mit schwächeren Signalen ergriffen werden. Bei diesem Ansatz müssen Sie einen Kompromiss zwischen der Notwendigkeit einer Standortschätzung und den Anforderungen an Genauigkeit und Wiedererkennung Ihrer Anwendung finden. Die folgenden Filtertechniken veranschaulichen, wie Eingaben gefiltert werden, zeigen aber nicht die Maßnahmen, die Sie als Anwendungsentwickler anwenden können.

Lokal verwaltete MAC-Adressen sind keine nützlichen Standortsignale für die API und werden aus Anfragen stumm ausgesondert. Sie können solche MAC-Adressen entfernen, indem Sie dafür sorgen, dass das zweitniedrigste Bit des höchstwertigen Bytes von macAddress 0 ist, z.B. das 1‑Bit, das durch das 2 in 02:00:00:00:00:00 dargestellt wird. Die MAC-Broadcastadresse (FF:FF:FF:FF:FF:FF) ist ein Beispiel für eine MAC-Adresse, die durch diesen Filter ausgeschlossen werden sollte.

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

Verwendbare MAC-Adressen für die Standortermittlung können beispielsweise aus einem Array von macAddress-Strings mit dem Namen macs erfasst 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');
    

Nach Anwendung dieses Filters 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 es wird eine HTTP-404-(notFound)-Antwort zurückgegeben.

Geocoding-Antworten

Bei einer erfolgreichen Anfrage für die Standortermittlung wird eine Antwort im JSON-Format zurückgegeben, 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 ist der Radius eines Kreises um die angegebene location.

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