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. Mit diesem Schlüssel wird Ihre Anwendung für die Kontingentverwaltung identifiziert. 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:

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; wird 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.
Bei CDMA wird die System-ID (SID) verwendet.		 Gültiger Bereich für MNC: 0–999.
Gültiger Bereich für SID: 0–32767.
radioType string Der Mobilfunktyp. Unterstützte Werte sind gsm, cdma, wcdma, lte und nr. Dieses Feld ist zwar optional, sollte aber immer angegeben werden, wenn der Funktyp dem Client bekannt ist.
Wenn das Feld ausgelassen wird, verwendet die Geolocation API standardmäßig gsm. Dies führt zu ungültigen oder leeren Ergebnissen, wenn der angenommene Funktyp falsch ist.
carrier string Der Name des Netzbetreibers.
considerIp boolean Gibt an, ob auf die IP-Geolokalisierung zurückgegriffen werden soll, wenn WLAN- und Mobilfunkmast-Signale fehlen, leer sind oder nicht ausreichen, um den Gerätestandort zu schätzen. Die Standardeinstellung ist true. Setzen Sie considerIp auf false, um ein Fallback zu verhindern.
cellTowers array Ein Array mit Mobilfunkmastobjekten. Weitere Informationen finden Sie unten im Abschnitt Mobilfunkmastobjekte.
wifiAccessPoints array Ein Array mit WiFi-Zugriffspunktobjekten. Weitere Informationen finden Sie unten im Abschnitt WiFi Access Point Objects (WLAN-Zugangspunktobjekte).

Unten sehen Sie ein Beispiel für einen Anfragetext für die Geolocation API.

{
  "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 des Anfrageinhalts enthält null oder mehr Mobilfunkmastobjekte.

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.
Weitere Informationen finden Sie unten im Abschnitt cellId berechnen. Dort sind auch die gültigen Wertebereiche für die einzelnen Funktypen aufgeführt.
newRadioCellId number (uint64) Eindeutige Kennung der NR-Zelle (5G). Erforderlich für radioType nr; abgelehnt für andere Typen.
Weitere Informationen finden Sie unten im Abschnitt newRadioCellId berechnen. Dort ist auch der gültige Wertebereich für das Feld aufgeführt.
locationAreaCode number (uint32) Der Location Area Code (LAC) für GSM- und WCDMA-Netzwerke.
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 mit nr: 0–16777215.
mobileCountryCode number (uint32) Der Mobile Country Code (MCC) des Mobilfunkmasts. Erforderlich für radioType gsm (Standard), wcdma, lte und nr; wird nicht für cdma verwendet.
Gültiger Bereich: 0–999.
mobileNetworkCode number (uint32) Die Mobilfunknetzkennzahl des Mobilfunkmasts. Dies ist der MNC für GSM, WCDMA, LTE und NR.
Bei CDMA wird die System-ID (SID) verwendet.		 Erforderlich.
Gültiger Bereich für MNC: 0–999.
Gültiger Bereich für 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, steht cellId oder newRadioCellId für eine aktuelle Messung.
signalStrength number (double) Die Stärke des Funksignals, gemessen in dBm.
timingAdvance number (double) Der Wert für Timing Advance.

cellId berechnen

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

  • GSM-Netzwerke (2G) verwenden die 16‑Bit-Zell‑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.
  • In WCDMA-Netzwerken (3G) wird die UTRAN/GERAN Cell Identity (UC-ID) verwendet, ein 28-Bit-Ganzzahlwert, der die 12-Bit-RNC-ID (Radio Network Controller Identifier) und die 16-Bit-CID (Cell ID) verknüpft.
    Formel: rnc_id << 16 | cid.
    Gültiger Bereich: 0–268435455.
    Hinweis:Wenn Sie in WCDMA-Netzwerken nur den 16-Bit-Wert für die Cell ID angeben, erhalten Sie falsche oder keine Ergebnisse.
  • In LTE-Netzwerken (4G) wird die E-UTRAN Cell Identity (ECI) verwendet, ein 28-Bit-Ganzzahlwert, der aus der 20-Bit-E-UTRAN Node B Identifier (eNBId) und der 8-Bit-Cell ID (CID) besteht.
    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 falsche oder keine Ergebnisse.

Wenn Sie Werte außerhalb dieser Bereiche in die API-Anfrage einfügen, kann dies zu einem undefinierten Verhalten führen. Die API kann die Zahl nach Ermessen von Google so kürzen, dass 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

Bei neueren Netzwerken, deren Zellen-IDs länger als 32 Bit sind, wird das 64-Bit-Feld newRadioCellId verwendet, um die Netzwerkzellen-ID 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-Mobilfunkmastobjekt.

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

WiFi-Zugriffspunktobjekte

Das wifiAccessPoints-Array des Anfragetexts muss mindestens zwei 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. Sie wird in der Regel als BSS, BSSID oder MAC-Adresse bezeichnet. Erforderlich: Durch Doppelpunkte (:) getrennter hexadezimaler String.
Über die API können nur universell verwaltete MAC-Adressen gefunden werden. Andere MAC-Adressen werden ohne Rückmeldung verworfen und können dazu führen, dass eine API-Anfrage leer ist. Weitere Informationen finden Sie unter Nutzlose WLAN-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, das Minuszeichen anzugeben.
Bei Werten über -10 dBm gibt die API NOT FOUND zurück.
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 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 testen 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
    }
  ]
}

Anschließend können Sie 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.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Nicht verwendete WLAN-Zugangspunkte entfernen

Wenn Sie WLAN-Zugangspunktobjekte mit macAddress 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-APs mit schwächeren Signalen ergriffen werden. Dieser Ansatz ist ein Kompromiss zwischen dem Bedarf Ihrer Anwendung an einer Standortschätzung und den Anforderungen an Genauigkeit und Recall. Die folgenden Filtertechniken zeigen, wie die Eingaben gefiltert werden, aber nicht die Maßnahmen, die Sie als Anwendungsentwickler ergreifen können.

Lokal verwaltete MAC-Adressen sind keine nützlichen Standortsignale für die API und werden in Anfragen ignoriert. Sie können solche MAC-Adressen entfernen, indem Sie dafür sorgen, dass das zweitniedrigstwertige Bit des höchstwertigen Byte von 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 sinnvoll ausgeschlossen werden könnte.

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 Netzwerkverwaltungs- und Multicastfunktionen verwendet, was ihre Verwendung als Standortsignal ausschließt. Sie sollten diese MAC-Adressen auch aus den Eingaben für die API entfernen.

Beispiel: Nutzbare MAC-Adressen für die Standortbestimmung können aus einem Array von macAddress-Strings mit dem Namen macs abgerufen 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');

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, wäre die Anfrage nicht erfolgreich und es würde eine HTTP-Antwort 404(notFound) zurückgegeben.

Geocoding-Antworten

Bei einer erfolgreichen Geolocation-Anfrage wird eine Antwort im JSON-Format zurückgegeben, in der ein Ort und ein Radius definiert sind.

  • 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 entspricht dem Radius eines Kreises um die angegebene location.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}