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-Parameter. Ein key ist die API-Schlüssel. Dieser Schlüssel identifiziert Ihre Anwendung für Kontingentzwecke zu verstehen. Weitere Informationen zum Abrufen eines Schlüssels

Anfragetext

Der Anforderungstext muss in JSON formatiert sein. Wenn der Anfragetext nicht enthalten ist, werden die Ergebnisse werden auf Basis der IP-Adresse des Anfragestandorts zurückgegeben. Die folgenden Felder sind unterstützt werden und 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 (Standardeinstellung), wcdma, lte und nr; nicht verwendet für cdma.
Gültiger Bereich: 0–999.
homeMobileNetworkCode number (uint32) Der Code des Mobilfunknetzes 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: gsm, cdma, wcdma, lte und nr. Dieses Feld ist zwar optional, sollte aber immer hinzugefügt werden, wenn der Funktyp der Kundschaft bekannt ist.
Wenn das Feld weggelassen wird, verwendet die Geolocation API standardmäßig gsm. Das führt zu ungültigen oder null Ergebnissen, wenn der angenommene Funktyp ist falsch.
carrier string Der Name des Netzbetreibers.
considerIp boolean Gibt an, ob auf die IP-Standortbestimmung zurückgegriffen werden soll, wenn WLAN- und Mobilfunkmastsignale fehlen. leer oder reicht nicht aus, um den Gerätestandort zu schätzen. Die Standardeinstellung ist true. considerIp festlegen auf false, um ein Fallback zu verhindern.
cellTowers array Ein Array mit Mobilfunkmastobjekten. Weitere Informationen finden Sie im Abschnitt Cell Tower-Objekte weiter unten.
wifiAccessPoints array Ein Array mit WiFi-Zugriffspunktobjekten. Weitere Informationen finden Sie im Abschnitt WiFi-Zugangspunktobjekte. weiter unten.

Unten sehen 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 Array cellTowers des Anfragetexts enthält null oder mehr von Mobilfunkmasten.

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.
Im Abschnitt Zellen-ID berechnen unten finden Sie ebenfalls eine Liste die gültigen Wertebereiche für jeden Radiotyp.
newRadioCellId number (uint64) Eindeutige Kennung der NR (5G)-Zelle. Erforderlich für radioType nr; abgelehnt für andere Typen.
Weitere Informationen finden Sie unten im Abschnitt NewRadioCellId berechnen. enthält auch den gültigen Wertebereich für das Feld.
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 (Standardeinstellung) und cdma, optional für andere Werte.
Gültiger Bereich mit gsm, cdma, wcdma und lte: 0–65.535
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) Der Code des Mobilfunknetzes 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 einbezogen werden, wenn Werte verfügbar.

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 einen aktuellen zu messen.
signalStrength number (double) Die Stärke des Funksignals, gemessen in dBm.
timingAdvance number (double) Die zeitvorbereitend Wert.

cellId wird berechnet

Funktypen vor NR (5G) verwenden das 32-Bit-Feld cellId zur Übergabe des Netzwerks Zellen-ID in die Geolocation API ein.

  • GSM-Netzwerke (2G) verwenden die 16-Bit-Zellen-ID (CID). Gültiger Bereich: 0–65.535.
  • CDMA-Netzwerke (2G) verwenden die 16-Bit-Basisstations-ID (BID). Gültiger Bereich: 0–65.535.
  • WCDMA-Netzwerke (3G) verwenden die UTRAN/GERAN Cell Identity (UC-ID), eine 28-Bit-Ganzzahl Wert zur Verkettung der 12-Bit-Radio Network Controller Identifier (RNC-ID) und der 16-Bit- Zellen-ID (CID).
    Formel: rnc_id << 16 | cid.
    Gültiger Bereich: 0–268435455.
    Hinweis: Wenn Sie nur den 16-Bit-Wert für die Cell ID in WCDMA-Netzwerken angeben, erhalten Sie oder keine Ergebnisse.
  • LTE-Netzwerke (4G) verwenden die E-UTRAN Cell Identity (ECI), ein 28-Bit-Ganzzahlwert. die 20-Bit-E-UTRAN Node B Identifier (eNBId) und die 8-Bit-Cell ID (CID) verketten.
    Formel: enb_id << 8 | cid.
    Gültiger Bereich: 0–268435455.
    Hinweis:Wenn Sie nur den 8-Bit-Wert für die Cell ID in LTE-Netzwerken angeben, erhalten Sie oder keine Ergebnisse.

Wenn in der API-Anfrage Werte außerhalb dieser Bereiche platziert werden, kann dies zu einem undefinierten Verhalten führen. Die API kann die Zahl nach Ermessen von Google kürzen, damit sie in den dokumentierten Bereich passt, und daraus ein Korrektur des radioTypes oder geben Sie ein NOT_FOUND-Ergebnis ohne in der Antwort angezeigt.

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
    }
  ]
}

Wird berechnet newRadioCellId

Neuere Netzwerke, deren Zellen-IDs länger als 32 Bit sind, verwenden die 64-Bit- Feld newRadioCellId zur Übergabe der Netzwerkzellen-ID an Geolocation API

  • NR-Netzwerke (5G) verwenden in der vorliegenden Form die 36-Bit-New Radio Cell Identity (NCI).
    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 Array wifiAccessPoints des Anfragetextes muss zwei oder mehr WiFi-Zugangspunktobjekte. macAddress ist erforderlich. alle andere 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.Durch Doppelpunkte getrennter Hexadezimalstring (:).
Nur allgemein verwaltet MAC-Adressen können über die API ermittelt werden. Andere MAC-Adressen sind wird ohne Meldung verworfen und kann dazu führen, dass eine API-Anfrage effektiv wird. leer. Weitere Informationen finden Sie unter Unnötigen WLAN-Zugriff sperren Punkte.
signalStrength number (double) Die aktuelle Signalstärke, gemessen in dBm. Für WLAN-Zugangspunkte liegen die dBm-Werte normalerweise bei -35 oder niedriger und liegen im Bereich von -128 bis -10 dBm. Vergessen Sie nicht das Minuszeichen.
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 einem Beispiel speichern Sie die folgende JSON-Datei 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
    }
  ]
}

Mit cURL können Sie dann Folgendes tun: Stellen Sie Ihre Anfrage über die Befehlszeile:

$ 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 vorangehenden MAC-Adressen sieht so aus:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Nicht verwendete WLAN-Zugangspunkte löschen

WiFi-Zugangspunktobjekte mit macAddress werden entfernt, die lokal verwaltet kann die Erfolgsquote 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 sind, sollten Abhilfemaßnahmen z. B. ältere Standortsignale oder WLAN-Zugangspunkte mit schwächere Signale verwendet werden können. Dieser Ansatz ist ein Kompromiss zwischen Anforderungen der Anwendung nach einer Standortschätzung und der Genauigkeit und Trefferquote Anforderungen. Die folgenden Filtertechniken zeigen, wie Sie Eingaben vor, aber zeigen nicht die möglichen Abhilfemaßnahmen, da die Anwendung anwenden möchten.

Lokal verwaltete MAC-Adressen sind keine nützlichen Standortsignale für den API und werden ohne Meldung aus den Anfragen entfernt. Sie können solche MAC-Adressen dass das zweitniedrigste Bit des Das bedeutendste Byte von macAddress ist 0, z.B. die 1 Bit, dargestellt durch 2 in 02:00:00:00:00:00 Die MAC-Adresse für die Übertragung (FF:FF:FF:FF:FF:FF) ist ein Beispiel für eine MAC-Adresse, die die von diesem Filter nützlich ausgeschlossen werden.

Der Bereich der MAC-Adressen zwischen 00:00:5E:00:00:00 und 00:00:5E:FF:FF:FF sind reserviert für IANA und wird häufig für die Netzwerkverwaltung und Multicast-Funktionen verwendet sodass sie nicht als Standortsignal genutzt werden können. Sie sollten auch diese MAC-Adressen aus Eingaben in die API

Nutzbare MAC-Adressen für die Standortbestimmung können beispielsweise aus einem Array von macAddress-Strings mit dem Namen macs:

<ph type="x-smartling-placeholder">
</ph>
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');

Mit diesem Filter werden nur 1c:34:56:78:9a:bc erzielt in der Liste verbleiben. Da diese Liste weniger als zwei WLAN-MAC-Adressen, nicht erfolgreich war, und der HTTP-Statuscode 404 (notFound) Antwort zurückgegeben.

Geocoding-Antworten

Bei einer erfolgreichen Anfrage zur Standortbestimmung wird eine Antwort im JSON-Format zurückgegeben. indem Sie einen Standort und einen Radius festlegen.

  • location: der geschätzte Breiten- und Längengrad des Nutzers -Koordinaten in Grad angeben. Enthält ein lat und ein lng untergeordneten Feld.
  • accuracy: Die Genauigkeit des ungefähren Standorts in Meter. Dies entspricht dem Radius eines Kreises um die gegebene location
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}