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:

Feld JSON-Typ Beschreibung Hinweise
homeMobileCountryCode number (uint32) Der Mobile Country Code (MCC) für das Heimnetzwerk des Geräts. Unterstützt für radioType gsm (Standard), wcdma, lte und nr; nicht für cdma verwendet.
Gültiger Bereich: 0–999.
homeMobileNetworkCode number (uint32) Die Mobilfunknetzkennzahl für das Heimnetzwerk des Geräts. Dies ist der MNC für GSM, WCDMA, LTE und NR.
CDMA verwendet die System-ID (SID)		 Gültiger Bereich für MNC: 0–999.
Gültiger Bereich für die SID: 0–32767.
radioType string Der Mobilfunktyp. Unterstützte Werte sind gsm, cdma, wcdma, lte und nr. Dieses Feld ist optional, sollte aber immer enthalten sein, wenn der Funkschnittstellentyp dem Client bekannt ist.
Wenn das Feld weggelassen wird, verwendet die Geolocation API standardmäßig gsm. Das führt zu ungültigen oder Nullergebnissen, wenn der angenommene Funktyp falsch ist.
carrier string Der Name des Netzbetreibers.
considerIp boolean Gibt an, ob auf die IP-Standortbestimmung zurückgegriffen werden soll, wenn WLAN- und Mobilfunkmastensignale fehlen, leer sind oder nicht ausreichen, um den Gerätestandort zu schätzen. Die Standardeinstellung ist true. Legen Sie considerIp auf false fest, um einen Rückfall zu verhindern.
cellTowers array Ein Array mit Mobilfunkmastobjekten. Weitere Informationen finden Sie unten im Abschnitt Funkmasten.
wifiAccessPoints array Ein Array mit WiFi-Zugriffspunktobjekten. Weitere Informationen finden Sie unten im Abschnitt Wi-Fi-Zugangspunktobjekte.

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.

Feld JSON-Typ Beschreibung Hinweise
cellId number (uint32) Die eindeutige Kennung der Funkzelle. Erforderlich für radioType, gsm (Standard), cdma, wcdma und lte; abgelehnt für nr.
Im Abschnitt Berechnen von „cellId“ unten finden Sie auch die gültigen Wertebereiche für jeden Radiotyp.
newRadioCellId number (uint64) Eindeutige Kennung der NR-Zelle (5G). Erforderlich für radioType nr; für andere Typen abgelehnt.
Im Abschnitt newRadioCellId berechnen unten finden Sie auch den gültigen Wertebereich für das Feld.
locationAreaCode number (uint32) Die Standortbereichsnummer (Location Area Code, LAC) für GSM- und WCDMA-Netze.
Die Netzwerk-ID (NID) für CDMA-Netzwerke.
Der Tracking Area Code (TAC) für LTE- und NR-Netzwerke.		 Erforderlich für radioType gsm (Standard) und cdma, optional für andere Werte.
Gültiger Bereich mit gsm, cdma, wcdma und lte: 0–65535.
Gültiger Bereich für nr: 0–16777215.
mobileCountryCode number (uint32) Der Mobile Country Code (MCC) des Mobilfunkmasts. Erforderlich für radioType gsm (Standard), wcdma, lte und nr; wird für cdma nicht verwendet.
Gültiger Bereich: 0–999.
mobileNetworkCode number (uint32) Der Mobilfunknetzcode des Mobilfunkmasts. Dies ist die MNC für GSM, WCDMA, LTE und NR.
Bei CDMA wird die System-ID (SID) verwendet.		 Erforderlich.
Gültiger Bereich für die Mobilfunkanbieterkennung: 0–999.
Gültiger Bereich für die SID: 0–32767.

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

Feld JSON-Typ Beschreibung Hinweise
age number (uint32) Die Anzahl Millisekunden, seit diese Funkzelle die primäre Funkzelle war. Wenn das Alter 0 ist, stellen cellId oder newRadioCellId eine aktuelle Messung dar.
signalStrength number (double) Die Stärke des Funksignals, gemessen in dBm.
timingAdvance number (double) Der Wert für den Zeitvorschuss.

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.

Feld JSON-Typ Beschreibung Hinweise
macAddress string Die MAC-Adresse des WLAN-Knotens. Diese Adresse wird in der Regel als BSS-, BSSID- oder MAC-Adresse bezeichnet. Erforderlich: Hexadezimalstring, der durch Doppelpunkte (:) getrennt ist.
Nur universell verwaltete MAC-Adressen können über die API ermittelt werden. Andere MAC-Adressen werden ohne Meldung gelöscht, was dazu führen kann, dass eine API-Anfrage effektiv leer wird. Weitere Informationen findest du unter Unnütze Wifi-Zugangspunkte entfernen.
signalStrength number (double) Die aktuelle Signalstärke, gemessen in dBm. Bei WLAN-Zugangspunkten liegen die dBm-Werte in der Regel bei -35 oder darunter und reichen von -128 bis -10 dBm. Achten Sie darauf, auch das Minuszeichen zu entfernen.
age number (uint32) Die Anzahl Millisekunden, seit dieser Zugriffspunkt gefunden wurde.
channel number (uint32) Der Kanal, über den der Client mit dem Zugriffspunkt kommuniziert.
signalToNoiseRatio number (double) Das aktuelle Signal-Rausch-Verhältnis, gemessen in dB.

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:

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

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
}