Anfrage und Antwort zur Standortbestimmung

Standortanfragen

Standortanfragen werden per 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 für die Kontingent verwaltung. 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 Mobilfunkländercode (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) Der Mobilfunknetzcode für das Heimnetzwerk des Geräts. Dies ist der MNC für GSM, WCDMA, LTE und NR.
CDMA verwendet die System-ID (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, es sollte aber immer angegeben werden, wenn der Funktyp dem Client bekannt ist.
Wenn das Feld weggelassen wird, verwendet die Geolocation API standardmäßig gsm, dies führt zu ungültigen oder keinen Ergebnissen, wenn der angenommene Funktyp falsch ist.
carrier string Der Name des Transportunternehmens.
considerIp boolean Gibt an, ob auf die IP-Standortbestimmung zurückgegriffen werden soll, wenn WLAN- und Mobilfunkmastsignale fehlen, leer sind oder nicht ausreichen, um den Gerätestandort zu schätzen. Standardmäßig true. Setzen Sie considerIp auf false , um den Rückgriff zu verhindern.
cellTowers array Ein Array mit Mobilfunkmastobjekten. Weitere Informationen finden Sie im Abschnitt Mobilfunkmastobjekte unten.
wifiAccessPoints array Ein Array mit WLAN-Zugangspunktobjekten. Weitere Informationen finden Sie im Abschnitt WLAN-Zugangspunktobjekte unten.

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

{
  "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 cellTowers-Array des Anfragetexts 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; für nr abgelehnt.
Weitere Informationen finden Sie im Abschnitt zum Berechnen von „cellId“ unten. Dort sind auch die gültigen Wertebereiche für jeden Funktyp aufgeführt.
newRadioCellId number (uint64) Die eindeutige Kennung der NR-Zelle (5G). Erforderlich für radioType nr; für andere Typen abgelehnt.
Weitere Informationen finden Sie im Abschnitt zum Berechnen von „newRadioCellId“ unten. 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 (Network 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 für gsm, cdma, wcdma und lte: 0–65535.
Gültiger Bereich für nr: 0–16777215.
mobileCountryCode number (uint32) Der Mobilfunkländercode (Mobile Country Code, MCC) des Mobilfunkmasts. Erforderlich für radioType gsm (Standard), wcdma, lte und nr; nicht für cdma verwendet.
Gültiger Bereich: 0–999.
mobileNetworkCode number (uint32) Der Mobilfunknetzcode des Mobilfunkmasts. Dies ist der MNC für GSM, WCDMA, LTE und NR.
CDMA verwendet die System-ID (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 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 „age“ 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 berechnen

Bei Funktypen vor NR (5G) wird das 32-Bit-cellId Feld verwendet, um die Netzwerk Zellen-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.
  • CDMA-Netzwerke (2G) verwenden die 16-Bit-Basisstations-ID (Base Station ID, BID) unverändert. Gültiger Bereich: 0–65535.
  • WCDMA-Netzwerke (3G) verwenden die UTRAN/GERAN Cell Identity (UC-ID). Das ist ein 28-Bit-Ganzzahlwert der aus der 12-Bit-Radio Network Controller ID (RNC-ID) und der 16-Bit Zellen-ID (CID) besteht.
    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, werden falsche oder keine Ergebnisse zurückgegeben.
  • LTE-Netzwerke (4G) verwenden die E-UTRAN Cell Identity (ECI). Das ist ein 28-Bit-Ganzzahlwert, der aus der 20-Bit-E-UTRAN Node B ID (eNBId) und der 8-Bit-Zellen-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 Zellen-ID angeben, werden falsche oder keine Ergebnisse zurückgegeben.

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

Unten sehen 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` berechnen newRadioCellId

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

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

Unten sehen 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 des Anfragetexts muss mindestens zwei WLAN-Zugangspunktobjekte enthalten, die physisch unterschiedliche stationäre Zugangspunktgeräte darstellen. Das Feld macAddress ist erforderlich. Alle anderen Felder sind optional. Der Dienst ignoriert sich bewegende Zugangspunkte, z. B. in Flugzeugen und Zügen.

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.
Mit der API können nur universell verwaltete MAC-Adressen ermittelt werden. Andere MAC-Adressen werden ohne Rückmeldung verworfen und können dazu führen, dass eine API-Anfrage effektiv leer wird. Weitere Informationen finden Sie unter Nutzlose WLAN-Zugangspunkte verwerfen.
signalStrength number (double) Die aktuelle Signalstärke, gemessen in dBm. Bei WLAN-Zugangspunkten liegen die dBm-Werte in der Regel bei -35 oder niedriger 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 gemessen in dB.

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

{
  ...
  
  "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 das folgende JSON 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 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 verwerfen

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 die Erfolgsrate von Geolocation API-Aufrufen verbessert werden, bei denen WLAN als Eingabe verwendet wird. Wenn nach dem Filtern festgestellt wird, dass ein Geolocation API-Aufruf nicht erfolgreich sein wird, können Maßnahmen wie die Verwendung älterer Standortsignale oder WLAN-Zugangspunkte mit schwächeren Signalen eingesetzt 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 Sie die Eingaben filtern können. Sie zeigen jedoch 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 reserviert für die IANA und wird häufig für die Netzwerkverwaltung und Multicast-Funktionen verwendet, daher können diese Adressen nicht als Standortsignal verwendet werden. Sie sollten diese MAC Adressen auch aus den Eingaben für 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 = {"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, ist die Anfrage nicht erfolgreich und es wird eine HTTP-404 (notFound) Antwort zurückgegeben.

Geolocation-Antworten

Bei einer erfolgreichen Standortanfrage wird eine JSON-formatierte Antwort zurückgegeben, 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 geschätzten Standorts in Metern. Dies stellt den Radius eines Kreises um den angegebenen location dar.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

Die API gibt einen Standort und einen Genauigkeitsradius basierend auf den Eingangssignalen zurück. Die API kann zwar 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 mindestens zwei wifiAccessPoints enthält, liegt der zurückgegebene Genauigkeitsradius in der Regel bei etwa 20 Metern. Die Genauigkeit verbessert sich mit der Anzahl der Zugangspunkte und stärkeren Signalen (gemessen in dBm). Die Signalstärken liegen in der Regel zwischen -100 und -20 dBm.
  • Mobilfunkmasten: Wenn keine oder nicht genügend WLAN-Informationen verfügbar sind, verwendet die API cellTowers für den Standort. Die Genauigkeit variiert erheblich je nach Mobilfunkmasttyp, Signalstärke und Netzdichte:
    • Makrozellen (der häufigste Typ, der für eine breite Abdeckung 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 in der Regel höher bei Mobilfunkmasten mit starken Signalen. 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).
    • Kleinzellen (z.B. Femtozellen, Picozellen oder Indoor Repeater) bieten den genauesten zellbasierten Standort mit Genauigkeits radien im Bereich von 10 bis 30 Metern.
  • IP-Standortbestimmung: Wenn considerIp auf true gesetzt ist und keine WLAN- oder Mobilfunkmastsignale geolokalisiert werden können, schätzt die API den Standort anhand der IP-Adresse der Anfrage. Diese Methode bietet die geringste Genauigkeit mit Radien von Tausenden von Metern. Weitere Informationen finden Sie im Leitfaden zur Fehlerbehebung unter Warum ist der Genauigkeitsradius sehr groß?