Es kann losgehen!

Bevor Sie mit der Entwicklung beginnen, lesen Sie bitte unsere Entwicklerdokumentation.

Die Google Maps Geolocation API aktivieren

Zum Einstieg führen wir Sie durch die Google Developers Console, wo Sie vorab Folgendes tun müssen:

  1. Ein Projekt erstellen oder auswählen
  2. Die Google Maps Geolocation API aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

Die Google Maps Geolocation API

Übersicht

Die Google Maps Geolocation API gibt den Standort und den Präzisionsradius basierend auf Daten von Mobilfunkmasten und WiFi-Knoten zurück, die von einem mobilen Client erkannt werden können. In diesem Dokument wird beschrieben, mit welchem Protokoll diese Daten an den Server übermittelt und eine Antwort an den Client zurückgegeben werden.

Die Kommunikation erfolgt über HTTPS mithilfe von POST. Sowohl Anforderung als auch Antwort sind in JSON formatiert und haben den Inhaltstyp application/json.

Bevor Sie mit der Durchführung von Entwicklungsaufgaben mit der Geolocation API beginnen, informieren Sie sich über die Authentifizierungsanforderungen (Sie benötigen einen API-Schlüssel) und die API-Nutzungsbeschränkungen.

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 Anforderung einen Schlüssel angeben, den Sie als Wert des Parameters key einfügen. Der key ist der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für das Kontingentmanagement. So können Sie einen Schlüssel anfordern.

Anforderungstext

Der Anforderungstext muss in JSON formatiert sein. Folgende Felder werden unterstützt, wobei alle optional sind:

  • homeMobileCountryCode: Der Mobile Country Code (MCC) des Heimnetzwerks des Geräts.
  • homeMobileNetworkCode: Der Mobile Network Code (MNC) des Heimnetzwerks des Geräts.
  • radioType: Der Mobilfunktyp. Unterstützte Werte sind lte, gsm, cdma und wcdma. Dieses Feld ist zwar optional, sollte für ein genaueres Ergebnis jedoch eingefügt werden, falls ein Wert verfügbar ist.
  • carrier: Der Name des Netzbetreibers.
  • considerIp: Gibt an, ob auf IP-Ortsbestimmung zurückgegriffen werden soll, wenn kein WiFi- oder Mobilfunksignal verfügbar ist. Beachten Sie jedoch, dass die IP-Adresse im Anforderungsheader ggf. nicht die IP des Geräts ist. Der Standardwert ist true. Legen Sie considerIp auf false fest, wenn Sie den Rückgriff auf IP-Ortsbestimmung deaktivieren möchten.
  • cellTowers: Ein Array mit Mobilfunkmastobjekten. Weitere Informationen finden Sie unten im Abschnitt Mobilfunkmastobjekte.
  • wifiAccessPoints: Ein Array mit WiFi-Zugriffspunktobjekten. Weitere Informationen finden Sie unten im Abschnitt WiFi-Zugriffspunktobjekte.
{
  "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 aus dem Anforderungstext enthält null oder mehr Mobilfunkmastobjekte.

  • cellId (erforderlich): Die eindeutige Kennung der Funkzelle. Im GSM-Netz ist dies die Cell-ID (CID), CDMA-Netze verwenden die Base Station ID (BID). WCDMA-Netze verwenden die UTRAN/GERAN Cell Identity (UC-Id), einen 32-Bit-Wert, der Radio Network Controller (RNC) und Cell ID miteinander verkettet. Wird nur der 16-Bit-Wert der Cell ID angegeben, kann dies bei WCDMA-Netzen zu ungenauen Ergebnissen führen.
  • locationAreaCode (erforderlich): Der Location Area Code (LAC) für GSM- und WCDMA-Netze. Die Network ID (NID) für CDMA-Netze.
  • mobileCountryCode (erforderlich): Der Mobile Country Code (MCC) des Mobilfunkmasts.
  • mobileNetworkCode (erforderlich): Der Mobile Network Code (MNC) des Mobilfunkmasts. Für GSM und WCDMA ist dies der MNC, für CDMA wird die System ID (SID) verwendet.

Die folgenden optionalen Felder werden derzeit nicht verwendet, können jedoch eingefügt werden, wenn Werte verfügbar sind.

  • age: Die Anzahl Millisekunden, seit diese Funkzelle die primäre Funkzelle war. Ist „age“ 0, stellt cellId eine aktuelle Messung dar.
  • signalStrength: Die Stärke des Funksignals, gemessen in dBm.
  • timingAdvance: Der Timing Advance-Wert.

Im Folgenden finden Sie ein Beispiel für ein GSM-Mobilfunkmastobjekt.

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

Im Folgenden finden Sie ein Beispiel für ein WCDMA-Mobilfunkmastobjekt.

{
  "cellTowers": [
    {
      "cellId": 21532831,
      "locationAreaCode": 2862,
      "mobileCountryCode": 214,
      "mobileNetworkCode": 7
    }
  ]
}

WiFi-Zugriffspunktobjekte

Das Array wifiAccessPoints im Anforderungstext muss mindestens zwei WiFi-Zugriffspunktobjekte enthalten. macAddress ist erforderlich, alle anderen Felder sind optional.

  • macAddress: (erforderlich) die MAC-Adresse des WiFi-Knotens. Als Trennzeichen muss : (Doppelpunkt) verwendet werden.
  • signalStrength: Die aktuelle Signalstärke, gemessen in dBm.
  • age: Die Anzahl Millisekunden, seit dieser Zugriffspunkt gefunden wurde.
  • channel: Der Kanal, über den der Client mit dem Zugriffspunkt kommuniziert.
  • signalToNoiseRatio: Das aktuelle Signal-Rausch-Verhältnis, gemessen in dB.

Im Folgenden finden Sie ein Beispiel für ein WiFi-Zugriffspunktobjekt.

{
  "macAddress": "00:25:9c:cf:1c:ac",
  "signalStrength": -43,
  "age": 0,
  "channel": 11,
  "signalToNoiseRatio": 0
}

Geocoding-Antworten

Bei einer erfolgreichen Geolocation-Anforderung wird eine in JSON formatierte Antwort zurückgegeben, durch die Standort und Radius definiert werden.

  • location: Der Standort des Benutzers als Längen- und Breitengradangabe. Enthält jeweils ein Unterfeld lat und lng.
  • accuracy: Die Genauigkeit des geschätzten Standorts in Metern. Dies ist der Radius eines Kreises um den jeweiligen Standort (location).
{
  "location": {
    "lat": 51.0,
    "lng": -0.1
  },
  "accuracy": 1200.4
}

Fehler

Treten Fehler auf, so wird eine Fehlermeldung im Standardformat zurückgegeben und der HTTP-Statuscode bekommt den Status „Fehler“.

Die Antwort enthält ein Objekt mit einem einzelnen Objekt error mit folgenden Schlüsseln:

  • code: Dies entspricht dem HTTP-Status der Antwort.
  • message: Eine kurze Beschreibung des Fehlers.
  • errors: Eine Liste der aufgetretenen Fehler. Jeder Fehler enthält eine Kennung für den Fehlertyp (reason) und eine kurze Beschreibung (message).

So wird bei ungültigem JSON-Format der folgende Fehler zurückgegeben.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

Im Folgenden finden Sie mögliche Fehler:

Grund Domäne HTTP-Statuscode Beschreibung
dailyLimitExceeded usageLimits 403 Sie haben Ihr Tageslimit überschritten.
keyInvalid usageLimits 400 Der API-Schlüssel ist für die Google Maps Geolocation API nicht gültig. Überprüfen Sie, ob Sie den gesamten Schlüssel eingegeben und die API entweder erworben oder die Abrechnung und die API aktiviert haben, um das kostenfreie Kontingent zu erhalten.
userRateLimitExceeded usageLimits 403 Sie haben das Limit für Anforderungen pro Sekunde und Nutzer überschritten, das Sie in der Google API Console konfiguriert haben. Dieses Limit sollte konfiguriert werden, um zu vermeiden, dass einzelne Benutzer oder kleine Gruppen von Benutzern Ihr Tageslimit aufbrauchen, und gleichzeitig allen Benutzern ausreichenden Zugriff zu ermöglichen.
notFound geolocation 404 Die Anforderung war gültig, aber es wurden keine Ergebnisse zurückgegeben.
parseError global 400 Der Anforderungstext weist nicht das gültige JSON-Format auf. Weitere Informationen zu jedem Feld der Anforderung finden Sie im Abschnitt Anforderungstext.

Beispielanforderungen

Wenn Sie die Google Maps Geolocation API mit einigen Beispieldaten ausprobieren möchten, speichern Sie folgenden JSON-Code in einer Datei:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
        "macAddress": "00:25:9c:cf:1c:ac",
        "signalStrength": -43,
        "signalToNoiseRatio": 0
    },
    {
        "macAddress": "00:25:9c:cf:1c:ad",
        "signalStrength": -55,
        "signalToNoiseRatio": 0
    }
  ]
}

Anschließend können Sie eine cURL verwenden, um Ihre Anforderung von der Befehlszeile aus durchzuführen:

$ 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 obigen Mac-Adressen sieht wie folgt aus:

{
  "location": {
    "lat": 33.3632256,
    "lng": -117.0874871
  },
  "accuracy": 20
}

Falls Sie keinen API-Schlüssel haben, nutzen Sie die Informationen unter Schlüssel anfordern.

Für weitere Tests können Sie mithilfe der Google Places API for Android und der Android Location APIs Informationen zu Ihrem Android-Gerät und mithilfe der Google Places API for iOS Informationen zu Ihrem iOS-Gerät erfassen.

Häufig gestellte Fragen

Weshalb ist der Radius der accuracy in meiner Geolocation-Antwort so groß?

Wird im Feld accuracy in Ihrer Geolocation-Antwort ein sehr hoher Wert angezeigt, wird die Geolokalisierung möglicherweise anhand der Anforderungs-IP und nicht anhand von WiFi-Zugriffspunkten oder Mobilfunkmasten durchgeführt. Dies kann passieren, wenn es keine gültigen Mobilfunkmasten oder Zugriffspunkte gibt oder keine erkannt wurden.

Um dies zu überprüfen, legen Sie considerIp in Ihrer Anforderung auf false fest. Lautet die Antwort 404, so ist damit bestätigt, dass die Objekte wifiAccessPoints und cellTowers nicht lokalisiert werden konnten.

Feedback geben zu...

Google Maps Geolocation API
Google Maps Geolocation API