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. key ist der API-Schlüssel Ihrer Anwendung. Anhand dieses Schlüssels wird Ihre Anwendung zur Kontingentverwaltung identifiziert. Weitere Informationen zum Abrufen eines Schlüssels

Anfragetext

Der Anforderungstext muss in JSON formatiert sein. Wenn der Anfragetext nicht enthalten ist, werden die Ergebnisse anhand 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 angegeben werden, wenn Werte verfügbar sind.

cellId berechnen

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-Zellen-ID (Cell ID, CID) unverändert. Gültiger Bereich: 0–65535.
• In CDMA-Netzwerken (2G) wird die 16-Bit-Basisstations-ID (BID) unverändert verwendet. 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 in WCDMA-Netzwerken nur den 16-Bit-Wert für die Zell-ID angeben, werden falsche Ergebnisse oder Nullergebnisse zurückgegeben.
• LTE-Netzwerke (4G) verwenden die E-UTRAN-Zellen-ID (ECI), eine 28-Bit-Ganzzahl, die 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 für die Cell ID angeben, erhalten Sie ein falsches Ergebnis oder null.

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 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-Mobilfunkmastenobjekt.

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

newRadioCellId wird berechnet

Neuere Netzwerke, deren Zell-IDs länger als 32 Bit sind, verwenden das 64-Bit-Feld newRadioCellId, 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 finden 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 zwei oder mehr WLAN-Zugangspunktobjekte enthalten, die physisch unterschiedliche Zugangspunktgeräte darstellen. 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 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
    }
  ]
}

Anschließend kannst du mit cURL die Anfrage über die Befehlszeile 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 Erfolgsquote von Geolocation API-Aufrufen verbessern, bei denen WLAN als Eingabe verwendet wird. Wenn nach dem Filtern festgestellt werden kann, dass ein API-Aufruf für die Standortbestimmung 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 Präzision und Rückruf Ihrer Anwendung finden. Die folgenden Filtertechniken zeigen, wie die Eingaben gefiltert werden, aber nicht die Abschwächungen, 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 ausgelassen. 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 Broadcast-MAC-Adresse (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 eine Verwendung als Standortsignal ausschließt. Außerdem sollten Sie diese MAC-Adressen aus den Eingaben an die API entfernen.

Verwendbare MAC-Adressen für die Standortbestimmung 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 JSON-Antwort zurückgegeben, in der ein Ort und ein Radius definiert werden.

• location: Die geschätzten Breiten- und Längengradkoordinaten 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 den angegebenen location.

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