Es kann losgehen!

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

Die Google Maps Elevation 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 Elevation API aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

Entwickler-Leitfaden

Über die Google Maps Elevation API erhalten Sie eine einfache Oberfläche, mit der Sie Höhendaten von Standorten auf der Erde abfragen können. Darüber hinaus können Sie per Intervall ermittelte Höhendaten für Pfade anfordern, sodass Sie die Höhenänderungen entlang von Routen berechnen können.

Dieser Dienst steht auch als Teil der clientseitigen Google Maps JavaScript API oder zur Verwendung auf Serverseite mit dem Java Client, Python Client, Go Client und Node.js Client for Google Maps Services zur Verfügung. Hinweis: Unabhängig davon, wie oft Sie den Dienst nutzen, gelten dieselben täglichen Nutzungsbeschränkungen. Die Anforderungen pro Tag werden als die Summe der clientseitigen und serverseitigen Abfragen berechnet.

Dieses Dokument richtet sich an Entwickler von Websites und mobilen Anwendungen, die Höhendaten in Karten verwenden möchten, die über Google Maps APIs bereitgestellt werden. Es enthält eine Einführung zur Verwendung der API und Informationen zu den verfügbaren Parametern.

Einführung

Mit Google Maps Elevation API erhalten Sie Höhendaten für alle Standorte auf der Erde, auch für „tiefe“ Orte am Meeresboden (dann werden negative Werte zurückgegeben). Falls Google keine exakten Höhenmessungen für den von Ihnen angeforderten präzisen Standort vorliegen, führt der Dienst eine Interpolation aus und gibt einen Durchschnittswert auf Basis der vier am nächsten gelegenen Standorte zurück. Die Höhenwerte werden relativ zum lokalen mittleren Meeresniveau (Local Mean Sea Level, LMSL) ausgedrückt.

Mithilfe von Google Maps Elevation API können Sie Anwendungen zum Wandern und Radfahren, für mobile Positionierung oder für Low-Resolution-Vermessungen entwickeln.

Sie greifen über eine HTTP-Schnittstelle auf Google Maps Elevation API zu. Nutzer von Google Maps JavaScript API können diese API auch direkt über das Objekt ElevationService() aufrufen. (Weitere Informationen finden Sie unter Elevation-Dienst.)

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

Höhenanforderungen

Google Maps Elevation API-Anforderungen werden als URL-Zeichenfolge erstellt. Von der API werden Höhendaten für Standorte auf der Erde zurückgegeben. Sie haben zwei Möglichkeiten, um die Standortdaten anzugeben:

  • Als Satz aus einem oder mehreren Standorten (locations).
  • Als Reihe verbundener Punkte entlang eines Pfads (path).

In beiden Fällen werden Längengrad- und Breitengradkoordinaten zur Bestimmung der Standorte oder Pfadeckpunkte herangezogen. In diesem Dokument werden das benötigte Format der URLs für Google Maps Elevation API und die verfügbaren Parameter beschrieben.

Von Google Maps Elevation API werden Daten für Einzelpunktabfragen mit der höchstmöglichen Präzision zurückgegeben. Bei Batch-Abfragen für mehrere Standorte werden ggf. weniger genaue Daten zurückgegeben. Das gilt aufgrund der Datenglättung besonders bei auseinanderliegenden Standorten.

Eine Google Maps Elevation API-Anforderung weist folgendes Format auf:

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

Dabei kann outputFormat einen der folgenden Werte haben:

  • json (empfohlen) gibt die Ausgabe in JavaScript Object Notation (JSON) an, oder
  • xml gibt die Ausgabe in XML an, in einem Knoten des Typs <ElevationResponse>.

Hinweis: URLs müssen ordnungsgemäß codiert sein, um gültig zu sein, und sind auf 8192 Zeichen für alle Webdienste beschränkt. Beachten Sie diese Beschränkung beim Erstellen Ihrer URLs. Zudem sollten Sie beachten, dass für verschiedene Browser, Proxys und Server ebenfalls unterschiedliche URL-Zeichenbegrenzungen gelten können.

HTTPS oder HTTP

Sicherheit ist wichtig und sofern möglich sollte HTTPS verwendet werden. Dies gilt insbesondere für Anwendungen, die in den Anforderungen persönliche Daten von Nutzern wie Standortangaben enthalten. Mit der HTTPS-Verschlüsselung wird Ihre Anwendung sicherer und ist besser vor Spionage und unbefugten Eingriffen geschützt.

Ist HTTPS nicht möglich, verwenden Sie für den Zugriff auf die Google Maps Elevation API über HTTP Folgendes:

http://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

Anforderungsparameter

In Anforderungen an Google Maps Elevation API werden unterschiedliche Parameter verwendet. Diese hängen davon ab, ob die Anforderung für einzelne Standorte oder für einen geordneten Pfad bestimmt ist. Im Falle von einzelnen Standorten werden von den Höhenanforderungen Daten zu den spezifischen Standorten, die in der Anforderung übergeben wurden, zurückgegeben. Bei Pfaden hingegen werden die Höhenanforderungen anhand von Intervallen entlang des vorgegebenen Pfads ermittelt.

Standardmäßig werden alle Parameter in URLs durch ein kaufmännisches Und (&) getrennt. Die Liste der Parameter und deren mögliche Werte sind unten aufgeführt.

Alle Anforderungen

  • key — (erforderlich) der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für das Kontingentmanagement. So können Sie einen Schlüssel anfordern.

    Hinweis: Google Maps APIs Premium Plan-Kunden können entweder einen API-Schlüssel oder eine gültige Client-ID und eine digitale Signatur in Ihren Elevation-Anforderungen verwenden. Lesen Sie weitere Informationen zu Authentifizierungsparametern für Premium Plan-Kunden.

Positionsanforderungen

  • Das Feld locations (erforderlich) definiert die Standorte auf der Erde, für die Höhendaten zurückgegeben werden sollen. In diesem Parameter wird ein einzelner Standort als durch Komma getrenntes {latitude,longitude}-Paar (z. B. „40.714728,-73.998672“) oder durch mehrere Längengrad- und Breitengradangaben angegeben, die als Array oder als kodierte Polylinie übergeben werden. Weitere Informationen finden Sie weiter unten unter Standorte angeben.

Pfadanforderungen per Intervall

  • Das Feld path (erforderlich) definiert einen Pfad auf der Erde, für den Höhendaten zurückgegeben werden sollen. In diesem Parameter werden zwei oder mehr geordnete {latitude,longitude}-Paare verwendet, die einen Pfad auf der Erdoberfläche definieren. Dieser Parameter muss zusammen mit dem Parameter samples verwendet werden, der weiter unten beschrieben wird. Weitere Informationen finden Sie weiter unten unter Pfade angeben.
  • Das Feld samples (erforderlich) gibt die Anzahl der Intervallpunkte entlang des Pfads an, für den Höhendaten zurückgegeben werden sollen. Mit dem Parameter samples wird das vorhandene Element path in einen geordneten Satz von abstandsgetreuen Punkten entlang des Pfads unterteilt.

Standorte angeben

Positionsanforderungen werden durch die Verwendung des Parameters locations gekennzeichnet, dabei werden Höhenanforderungen für die angegebenen Standorte als Längengrad- und Breitengradwerte angegeben.

Für den Parameter locations sind die folgenden Argumente möglich:

  • Einzelkoordinaten: locations=40.714728,-73.998672
  • Array von Koordinaten, getrennt durch einen senkrechten Strich (|): locations=40.714728,-73.998672|-34.397,150.644
  • Satz mit kodierten Koordinaten unter Verwendung des kodierten Polylinienalgorithmus: locations=enc:gfo}EtohhU

Längengrad- und Breitengradkoordinaten werden anhand von Zahlen in einer durch Komma getrennten Zeichenfolge definiert. Beispielsweise ist „40.714728,-73.998672“ ein zulässiger Wert für locations. Die Längengrad- und Breitengradangaben müssen einem vorhandenen Standort auf der Erde entsprechen. Für den Breitengrad sind Werte zwischen -90 und 90 zulässig, für den Längengrad können Werte zwischen -180 und 180 angegeben werden. Falls Sie einen unzulässigen Wert für den Längengrad oder den Breitengrad eingeben, wird Ihre Anforderung als fehlerhaft zurückgewiesen.

Beim Erstellen einer gültigen URL können Sie in einem Array oder in einer kodierten Polylinie eine beliebige Anzahl von mehreren Koordinaten übergeben, sofern Sie nicht die Servicekontingente überschreiten. Beachten Sie, dass beim Übergeben von mehreren Koordinaten die Genauigkeit der zurückgegebenen Daten eine niedrigere Auflösung aufweist, als wenn Sie Daten für Einzelkoordinaten anfordern.

Pfade angeben

Pfadanforderungen per Intervall werden durch die Verwendung der Parameter path und samples gekennzeichnet, dabei werden Höhendaten entlang eines Pfads mit definierten Intervallen angefordert. Wie bei Positionsanforderungen, für die der Parameter locations genutzt wird, wird auch für den Parameter path ein Satz aus Längengrad- und Breitengradwerten verwendet. Allerdings wird im Parameter path ein geordneter Satz an Eckpunkten spezifiziert. Anstatt die Höhendaten nur für die Eckpunkte zurückzugeben, werden bei Pfadanforderungen per Intervall die Daten über die Pfadlänge angegeben, und zwar auf Basis der definierten Werte für samples (einschließlich der Endpunkte).

Für den Parameter path ist eines der folgenden Argumente möglich:

  • Ein Array mit zwei oder mehr durch Komma getrennten Koordinaten, die Zeichenfolgen werden durch einen senkrechten Strich (|) getrennt: path=40.714728,-73.998672|-34.397,150.644
  • Kodierte Koordinaten unter Verwendung des kodierten Polylinienalgorithmus: path=enc:gfo}EtohhUxD@bAxJmGF

Längengrad- und Breitengradkoordinaten werden anhand von Zahlen in einer durch Komma getrennten Zeichenfolge definiert. Beispielsweise ist die Angabe „40.714728,-73.998672|-34.397, 150.644“ ein zulässiger Wert für path. Die Längengrad- und Breitengradangaben müssen einem vorhandenen Standort auf der Erde entsprechen. Für den Breitengrad sind Werte zwischen -90 und 90 zulässig, für den Längengrad können Werte zwischen -180 und 180 angegeben werden. Falls Sie einen unzulässigen Wert für den Längengrad oder den Breitengrad eingeben, wird Ihre Anforderung als fehlerhaft zurückgewiesen.

Beim Erstellen einer gültigen URL können Sie in einem Array oder in einer kodierten Polylinie eine beliebige Anzahl von mehreren Koordinaten übergeben, sofern Sie nicht die Servicekontingente überschreiten. Beachten Sie, dass beim Übergeben von mehreren Koordinaten die Genauigkeit der zurückgegebenen Daten eine niedrigere Auflösung aufweist, als wenn Sie Daten für Einzelkoordinaten anfordern.

Höhenantworten

Für jede zulässige Anforderung gibt der Elevation-Dienst eine Elevation-Antwort im Format, das in der Anforderungs-URL angegeben ist. In jeder Antwort sind die folgenden Elemente enthalten:

Ein Elevation-Statuscode (status) mit einem der folgenden Werte:

  • OK gibt an, dass die API-Anforderung erfolgreich war.
  • INVALID_REQUEST gibt an, dass die API-Anforderung fehlerhaft formatiert war.
  • OVER_QUERY_LIMIT gibt an, dass der Anforderer sein Kontingent überschritten hat.
  • REQUEST_DENIED gibt an, dass die API-Anforderung nicht ausgeführt wurde.
  • UNKNOWN_ERROR gibt an, dass ein unbekannter Fehler vorliegt.

Bei einem anderen Statuscode als OK wird ggf. im Elevation-Antwortobjekt ein weiteres Feld error_message angezeigt. Dieses Feld enthält weitere detaillierte Informationen zu den Gründen für den zurückgegebenen Statuscode.

Hinweis: Dieses Feld wird nicht immer angezeigt, und sein Inhalt unterliegt Änderungen.

In einem Array von results sind die folgenden Elemente enthalten:

  • Ein Element des Typs location (in dem die Elemente lat und lng enthalten sind) mit der Position, für die Höhendaten berechnet werden sollen. Beachten Sie, dass bei Pfadanforderungen im Satz der Elemente location die Intervallpunkte entlang des Pfads enthalten sind.
  • Ein Element des Typs elevation, mit dem die Höhe des Standorts in Metern angegeben wird.
  • Ein Wert für resolution, mit dem die maximale Entfernung zwischen den Datenpunkten, anhand derer die Höhe interpoliert wurde, in Metern angegeben wird. Falls die Auflösung nicht bekannt ist, fehlt diese Eigenschaft. Beachten Sie, dass bei der Übergabe von mehreren Punkten die Höhendaten gröber werden (höhere Werte für resolution). Ein Punkt sollte einzeln abgefragt werden, um den präzisesten Höhenwert zu erhalten.

Positionsbezogene Höhendaten – Beispiele

Im folgenden Beispiel wird die Höhe für Denver, Colorado, die „Mile High City“ im JSON-Format angefordert:

https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034&key=YOUR_API_KEY
{
   "results" : [
      {
         "elevation" : 1608.637939453125,
         "location" : {
            "lat" : 39.73915360,
            "lng" : -104.98470340
         },
         "resolution" : 4.771975994110107
      }
   ],
   "status" : "OK"
}

Im folgenden Beispiel werden mehrere Antworten (für Denver, CO, und für Death Valley, CA) angezeigt.

In dieser Anforderung wird die Verwendung des JSON-Flags output veranschaulicht:

https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

In dieser Anforderung wird die Verwendung des XML-Flags output veranschaulicht:

https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

Klicken Sie unten auf die jeweilige Registerkarte, um sich die Beispielantworten in JSON und XML anzusehen.

JSON
{
   "results" : [
      {
         "elevation" : 1608.637939453125,
         "location" : {
            "lat" : 39.73915360,
            "lng" : -104.98470340
         },
         "resolution" : 4.771975994110107
      },
      {
         "elevation" : -50.78903579711914,
         "location" : {
            "lat" : 36.4555560,
            "lng" : -116.8666670
         },
         "resolution" : 19.08790397644043
      }
   ],
   "status" : "OK"
}
XML
<?xml version="1.0" encoding="UTF-8"?>
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
 <result>
  <location>
   <lat>36.4555560</lat>
   <lng>-116.8666670</lng>
  </location>
  <elevation>-50.7890358</elevation>
  <resolution>19.0879040</resolution>
 </result>
</ElevationResponse>

In den folgenden Beispielen werden Höhendaten entlang einer geraden Linie mit path von Mt. Whitney, CA, nach Badwater, CA, angefordert, dem höchsten und dem niedrigsten Punkt des US-amerikanischen Festlands. Es werden drei Intervalle über samples angefordert, sodass die beiden Endpunkte und ein Punkt auf halber Strecke einbezogen werden.

https://maps.googleapis.com/maps/api/elevation/json?path=36.578581,-118.291994|36.23998,-116.83171&samples=3&key=YOUR_API_KEY
{
   "results" : [
      {
         "elevation" : 4411.941894531250,
         "location" : {
            "lat" : 36.5785810,
            "lng" : -118.2919940
         },
         "resolution" : 19.08790397644043
      },
      {
         "elevation" : 1381.861694335938,
         "location" : {
            "lat" : 36.41150289067028,
            "lng" : -117.5602607523847
         },
         "resolution" : 19.08790397644043
      },
      {
         "elevation" : -84.61699676513672,
         "location" : {
            "lat" : 36.239980,
            "lng" : -116.831710
         },
         "resolution" : 19.08790397644043
      }
   ],
   "status" : "OK"
}

Höhendiagramme erstellen

Die Höhendaten müssen auf einer Google-Karte angezeigt werden. Zum Erstellen von Höhendiagrammen, die Sie zusammen mit den Karten anzeigen können, ist „Chart API“ (https://code.google.com/apis/chart/) sehr gut geeignet.

Im folgenden Python-Beispiel werden die Höhendaten zwischen Mt. Whitney und Badwater, Death Valley, berechnet. Auf Basis dieser Werte wird ein Höhendiagramm erstellt:

import simplejson
import urllib

ELEVATION_BASE_URL = 'https://maps.googleapis.com/maps/api/elevation/json'
CHART_BASE_URL = 'https://chart.apis.google.com/chart'

def getChart(chartData, chartDataScaling="-500,5000", chartType="lc",chartLabel="Elevation in Meters",chartSize="500x160",chartColor="orange", **chart_args):
    chart_args.update({
      'cht': chartType,
      'chs': chartSize,
      'chl': chartLabel,
      'chco': chartColor,
      'chds': chartDataScaling,
      'chxt': 'x,y',
      'chxr': '1,-500,5000'
    })

    dataString = 't:' + ','.join(str(x) for x in chartData)
    chart_args['chd'] = dataString.strip(',')

    chartUrl = CHART_BASE_URL + '?' + urllib.urlencode(chart_args)

    print chartUrl

    def getElevation(path="36.578581,-118.291994|36.23998,-116.83171",samples="100", **elvtn_args):
      elvtn_args.update({
        'path': path,
        'samples': samples
      })

      url = ELEVATION_BASE_URL + '?' + urllib.urlencode(elvtn_args)
      response = simplejson.load(urllib.urlopen(url))

      # Create a dictionary for each results[] object
      elevationArray = []

      for resultset in response['results']:
        elevationArray.append(resultset['elevation'])

      # Create the chart passing the array of elevation data
      getChart(chartData=elevationArray)

if __name__ == '__main__':
    # Mt. Whitney
    startStr = "36.578581,-118.291994"
    # Death Valley
    endStr = "36.23998,-116.83171"

    pathStr = startStr + "|" + endStr

    getElevation(pathStr)

Auf den folgenden Bildern wird veranschaulicht, wie diese Daten auf einer Karte und/oder in einem Diagramm dargestellt werden können:

Download: Code ElevationChartCreator.py von js-v2-samples.

Der Parameter sensor

Bisher war in der Google Maps API die Angabe des Parameters sensor erforderlich. Damit wurde festgelegt, ob seitens der Anwendung ein Sensor zur Ermittlung des Benutzerstandorts verwendet wurde. Dieser Parameter wird nicht mehr benötigt.

Feedback geben zu...

Google Maps Elevation API
Google Maps Elevation API