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 als Wert eines key-Parameters angeben. key ist der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für die Kontingentverwaltung. 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 Standorts der Anfrage zurückgegeben. Die folgenden Felder werden unterstützt. Alle Felder sind optional, sofern nicht anders angegeben:

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 verwendet für cdma.
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 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 Client den Funktyp kennt.
Wenn das Feld weggelassen wird, verwendet die Geolocation API standardmäßig gsm. Das führt zu ungültigen oder keinen Ergebnissen, wenn der angenommene Funktyp falsch ist.
carrier string Der Name des Netzbetreibers.
considerIp boolean Gibt an, ob auf die IP-Standortermittlung zurückgegriffen werden soll, wenn WLAN- und Mobilfunkmastsingale fehlen, leer oder nicht ausreichend sind, 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 Mobilfunkmast-Objekte.
wifiAccessPoints array Ein Array von WLAN-Zugangspunktobjekten. Weitere Informationen finden Sie unten im Abschnitt WLAN-Zugangspunktobjekte.

Im Folgenden finden Sie ein Beispiel für einen Geolocation API-Anfragetext.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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 im Anfragetext enthält null oder mehr Mobilfunkmast-Objekte.

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; für andere Typen abgelehnt.
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; nicht verwendet für cdma.
Gültiger Bereich: 0–999.
mobileNetworkCode number (uint32) Die Mobilfunknetzkennzahl des Mobilfunkmasts. Dies ist der MNC für GSM, WCDMA, LTE und NR.
CDMA verwendet die System-ID (SID).		 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 enthalten sein, 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, stellt 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 Timing Advance.

cellId wird berechnet

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-Zellen-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.
  • WCDMA-Netzwerke (3G) verwenden die UTRAN/GERAN-Zell-ID (UC-ID). Dies ist ein 28-Bit-Ganzzahlwert, der die 12-Bit-Radio Network Controller-ID (RNC-ID) und die 16-Bit-Zell-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 Zellen-ID angeben, führt dies zu falschen oder keinen Ergebnissen.
  • LTE-Netzwerke (4G) verwenden die E-UTRAN Cell Identity (ECI). Dies ist ein 28-Bit-Ganzzahlwert, der die 20-Bit-E-UTRAN Node B Identifier (eNBId) und die 8-Bit-Cell ID (CID) verkettet.
    Formel: enb_id << 8 | cid.
    Gültiger Bereich: 0–268435455.
    Hinweis: Wenn Sie in LTE-Netzwerken nur den 8-Bit-Wert für die Zellen-ID angeben, führt dies zu falschen oder keinen Ergebnissen.

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

Unten finden Sie ein Beispiel für ein LTE-Mobilfunkmastobjekt, das Teil des Anfragetexts ist.

{
  ...

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

Die Antwort auf die vorherige Anfrage sieht so aus:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

newRadioCellId wird berechnet

Neuere Netzwerke, deren Zellen-IDs länger als 32 Bit sind, verwenden das 64-Bit-Feld newRadioCellId, um die Zellen-ID des Netzwerks an die Geolocation API zu übergeben.

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

Unten finden Sie ein Beispiel für ein NR-Mobilfunkmastobjekt, das Teil des Anfragetexts ist.

{
  ...

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

Die Antwort auf die vorherige Anfrage sieht so aus:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

WLAN-Zugangspunktobjekte

Das wifiAccessPoints-Array im Anfragetext muss mindestens zwei WLAN-Zugangspunktobjekte enthalten, die physisch unterschiedliche stationäre Zugangspunkte darstellen. Das Feld macAddress ist erforderlich. Alle anderen sind optional. Der Dienst ignoriert Zugangspunkte, die sich bewegen, z. B. in Flugzeugen und Zügen.

Feld JSON-Typ Beschreibung Hinweise
macAddress string Die MAC-Adresse des WLAN-Knotens. Sie wird normalerweise als BSS, BSSID oder MAC-Adresse bezeichnet. Erforderlich. Durch Doppelpunkte (:) getrennter Hexadezimalstring.
Über die API können nur universell verwaltete MAC-Adressen gefunden werden. Andere MAC-Adressen werden stillschweigend verworfen, was dazu führen kann, dass eine API-Anfrage effektiv leer ist. Weitere Informationen finden Sie unter Unbrauchbare WLAN-Zugangspunkte verwerfen.
signalStrength number (double) Die aktuelle Signalstärke, gemessen in dBm. Bei WLAN-Zugangspunkten liegen die dBm-Werte normalerweise bei -35 oder niedriger und reichen von -128 bis -10 dBm. Vergessen Sie nicht, 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.

Unten sehen Sie ein Beispiel für ein WLAN-Zugangspunktobjekt, das Teil des Anfragetexts ist.

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

Die Antwort auf die vorherige Anfrage sieht so aus:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

Beispielanforderungen

Wenn Sie die Geolocation API mit Beispieldaten testen 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 können Sie 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 werden gelöscht

Wenn Sie WLAN-Zugangspunktobjekte mit macAddressen entfernen, die entweder eine Broadcast-Adresse (FF:FF:FF:FF:FF:FF) sind oder von der IANA reserviert wurden, kann sich die Erfolgsquote von Geolocation API-Aufrufen verbessern, die WLAN als Eingabe verwenden. Wenn nach dem Filtern festgestellt wird, 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 Trefferquote. Die folgenden Filtertechniken zeigen, wie Sie die Eingaben filtern, aber nicht die Maßnahmen, die Sie als Anwendungsentwickler möglicherweise anwenden möchten.

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 Multicast-Funktionen verwendet, sodass sie nicht als Standortsignal verwendet werden können. Außerdem sollten Sie diese MAC-Adressen aus den Eingaben für die API entfernen.

Beispielsweise können verwendbare MAC-Adressen für die Standortbestimmung aus einem Array von macAddress-Strings mit dem Namen macs abgerufen werden:

Java
String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
Python
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
JavaScript
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && m.substr(0, 8).toUpperCase() !== '00:00:5E');

Wenn Sie diesen Filter verwenden, bleibt 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-404-(notFound)-Antwort zurückgegeben werden.

Geocoding-Antworten

Eine erfolgreiche Standortanfrage gibt eine Antwort im JSON-Format zurück, die einen Standort und einen Radius definiert.

  • location: Die geschätzten Breiten- und Längengradkoordinaten des Nutzers in Grad. Enthält ein lat- und ein lng-Unterfeld.
  • accuracy: Die Genauigkeit des ungefähren Standorts in Metern. Dies ist der Radius eines Kreises um den angegebenen location.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Die API gibt einen Standort und einen Genauigkeitsradius basierend auf den Eingabesignalen zurück. Die API kann einen sehr genauen Standort zurückgeben, die Genauigkeit kann jedoch je nach Quelle, Anzahl, Dichte und Stärke der verfügbaren Signale variieren. In der Regel können Sie mit den folgenden Genauigkeitsradien rechnen:

  • WLAN-Zugangspunkte: Wenn die Anfrage zwei oder mehr wifiAccessPoints enthält, beträgt der zurückgegebene Genauigkeitsradius in der Regel etwa 20 Meter. Die Genauigkeit verbessert sich mit der Anzahl der Zugangspunkte und stärkeren Signalen (gemessen in dBm). Die Signalstärke liegt in der Regel zwischen -100 und -20 dBm.
  • Mobilfunkmasten: Wenn keine WLAN-Informationen verfügbar oder diese unzureichend sind, verwendet die API cellTowers für die Standortbestimmung. Die Genauigkeit variiert je nach Mobilfunkmasttyp, Signalstärke und Netzwerkdichte erheblich:
    • Makrozellen (der gängigste Typ, der für die Abdeckung großer Bereiche verwendet wird) bieten eine geringere Genauigkeit. Der Radius liegt in der Regel im Bereich von Hunderten von Metern und kann in Gebieten mit geringer Mobilfunkmastabdeckung bis zu mehreren Tausend Metern betragen. Bei Makrozellen ist es ungewöhnlich, einen Genauigkeitsradius von weniger als 100 Metern zu erreichen. Die Genauigkeit ist bei Mobilfunkmasten mit starken Signalen im Allgemeinen höher. Starke Signale sind in der Regel > -110 dBm für LTE (Signalbereich -140 bis -55 dBm), > -100 dBm für WCDMA (Signalbereich -111 bis -53 dBm), > -100 dBm für CDMA (Signalbereich -120 bis -40 dBm) und > -80 dBm für GSM (Signalbereich -121 bis -1 dBm).
    • Small Cells (z.B. Femtozellen, Pikozellen oder Indoor-Repeater) liefern die genauesten mobilfunkbasierten Standortdaten mit einem Genauigkeitsradius von 10 bis 30 Metern.
  • IP-Geolokalisierung: Wenn considerIp den Wert true hat und keine WLAN- oder Mobilfunkmastsingale geolokalisiert werden können, schätzt die API den Standort anhand der IP-Adresse der Anfrage. Diese Methode bietet die geringste Genauigkeit mit Radien, die Tausende von Metern betragen können. Weitere Informationen finden Sie unter Warum ist der Genauigkeitsradius sehr groß?. in der Anleitung zur Fehlerbehebung.