Höhenanfragen und -antworten

Höhendaten anfragen

Elevation API-Anfragen werden als URL-String erstellt. Die API gibt Höhendaten für Standorte auf der Erde zurück. Sie können Standortdaten auf zwei Arten angeben:

  • Als Satz von einem oder mehreren locations.
  • Als Reihe verbundener Punkte entlang einer path.

Bei beiden Ansätzen werden die Orte oder Pfadscheitelpunkte anhand von Breiten- und Längengraden identifiziert. In diesem Dokument werden das erforderliche Format von Elevation API-URLs und die verfügbaren Parameter beschrieben.

Die Elevation API gibt Daten für Einzelpunktabfragen mit der höchstmöglichen Genauigkeit zurück. Batchabfragen, die mehrere Standorte umfassen, können Daten mit geringerer Genauigkeit zurückgeben, insbesondere wenn die Standorte weit voneinander entfernt sind, da die Daten etwas geglättet werden.

Eine Elevation API-Anfrage hat folgendes Format:

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

Dabei kann outputFormat einer der folgenden Werte sein:

  • json (empfohlen) gibt die Ausgabe in JavaScript Object Notation (JSON) an.
  • xml gibt die Ausgabe im XML-Format an, eingebettet in einen <ElevationResponse>-Knoten.

Hinweis: URLs müssen ordnungsgemäß codiert sein, um gültig zu sein, und sind für alle Webdienste auf 16.384 Zeichen beschränkt. Beachten Sie dieses Limit beim Erstellen Ihrer URLs. Beachten Sie, dass verschiedene Browser, Proxys und Server auch unterschiedliche Zeichenbeschränkungen für URLs haben können.

Bei Anfragen mit API-Schlüssel ist HTTPS erforderlich.

Anfrageparameter

Anfragen an die Elevation API verwenden unterschiedliche Parameter, je nachdem, ob die Anfrage für einzelne Standorte oder für einen geordneten Pfad gilt. Bei einzelnen Orten werden die Höhendaten für die in der Anfrage angegebenen Orte zurückgegeben. Bei Pfaden werden die Höhendaten stattdessen an Punkten erhoben, die in gleichmäßigen Abständen auf den gesamten Pfad verteilt sind.

Wie in URLs üblich, werden alle Parameter mit dem Und-Zeichen (&amp;) getrennt. Die Liste der Parameter und ihre möglichen Werte sind unten aufgeführt.

Alle Anfragen

Positionsanfragen

  • locations (erforderlich): definiert die Standorte auf der Erde, für die Höhendaten zurückgegeben werden sollen. Dieser Parameter akzeptiert entweder einen einzelnen Ort als kommagetrenntes Paar aus Breiten- und Längengrad (z.B. „40.714728,-73.998672“) oder mehrere Paare aus Breiten- und Längengrad, die als Array oder als codierte Polylinie übergeben werden. Für diesen Parameter gilt ein Limit von 512 Punkten. Weitere Informationen finden Sie unten unter Standorte angeben.

Anfragen für Pfade mit Stichproben

  • path (erforderlich): definiert einen Pfad auf der Erde, für den Höhendaten zurückgegeben werden sollen. Dieser Parameter definiert einen Satz von zwei oder mehr geordneten Paaren aus Breiten- und Längengrad,die einen Pfad entlang der Erdoberfläche definieren. Dieser Parameter muss in Verbindung mit dem unten beschriebenen Parameter samples verwendet werden. Für diesen Parameter gilt ein Limit von 512 Punkten. Weitere Informationen finden Sie unten unter Pfade angeben.
  • samples (erforderlich): gibt die Anzahl der Beispielpunkte entlang eines Pfades an, für die Höhendaten zurückgegeben werden sollen. Der samples-Parameter unterteilt den angegebenen path in einen geordneten Satz von Punkten, die sich in gleichen Abständen entlang des Pfades befinden.

Standorte angeben

Positionsanfragen werden durch den Parameter locations gekennzeichnet. Damit werden Höhenanfragen für die angegebenen Standorte gestellt, die als Breiten- und Längengradwerte übergeben werden.

Der Parameter locations kann die folgenden Argumente annehmen:

  • Eine einzelne Koordinate: locations=40.714728,-73.998672
  • Ein Array von Koordinaten, die durch einen senkrechten Strich (|) getrennt sind: locations=40.714728,-73.998672|-34.397,150.644
  • Eine Reihe codierter Koordinaten, die mit dem Algorithmus für codierte Polylinien codiert wurden: locations=enc:gfo}EtohhU

Koordinatenstrings für Breiten- und Längengrade werden mit Ziffern in einem kommagetrennten Textstring definiert. Beispiel: „40.714728,-73.998672“ ist ein gültiger locations-Wert. Die Werte für Breiten- und Längengrad müssen einem gültigen Ort auf der Erde entsprechen. Breitengrade können einen beliebigen Wert zwischen -90 und 90 annehmen, während Längengrade einen beliebigen Wert zwischen -180 und 180 annehmen können. Wenn Sie einen ungültigen Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als ungültige Anfrage abgelehnt.

Sie können bis zu 512 Koordinaten in einem Array oder einer codierten Polylinie übergeben und trotzdem eine gültige URL erstellen. Wenn mehrere Koordinaten weitergegeben werden, sind die zurückgegebenen Daten möglicherweise ungenauer, als wenn Sie Daten für Einzelkoordinaten anfordern. Wenn die Parameter „locations“ oder „path“ mehr als 512 Punkte oder Koordinaten enthalten, wird die Antwort INVALID_REQUEST zurückgegeben.

Pfade angeben

Anfragen für einen Pfad mit Stichproben werden durch die Parameter path und samples gekennzeichnet. Damit werden Höhendaten entlang eines Pfads in bestimmten Intervallen angefordert. Wie bei Positionsanfragen mit dem Parameter locations wird mit dem Parameter path ein Satz von Breiten- und Längengradwerten angegeben. Anders als bei Positionsanfragen wird mit dem path-Parameter jedoch ein geordneter Satz von Eckpunkten angegeben. Es werden aber keine Höhendaten nur für die Eckpunkte geliefert, sondern die Daten werden an Punkten erhoben, die in gleichmäßigen Abständen auf den gesamten Pfad verteilt sind, einschließlich der Endpunkte. Die Anzahl der Punkte wird durch samples angegeben.

Der Parameter path kann eines der folgenden Argumente annehmen:

  • Ein Array aus zwei oder mehr kommagetrennten Koordinaten-Strings, die durch einen senkrechten Strich (|) getrennt sind: path=40.714728,-73.998672|-34.397,150.644
  • Codierte Koordinaten mit dem Algorithmus für codierte Polylinien: path=enc:gfo}EtohhUxD@bAxJmGF

Koordinatenstrings für Breiten- und Längengrade werden mit Ziffern in einem kommagetrennten Textstring definiert. Beispiel: „40.714728,-73.998672|-34.397, 150.644“ ist ein gültiger path-Wert. Breiten- und Längengradwerte müssen einem gültigen Ort auf der Erde entsprechen. Breitengrade können einen beliebigen Wert zwischen -90 und 90 annehmen, während Längengrade einen beliebigen Wert zwischen -180 und 180 annehmen können. Wenn Sie einen ungültigen Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als ungültige Anfrage abgelehnt.

Sie können bis zu 512 Koordinaten in einem Array oder einer codierten Polylinie übergeben und trotzdem eine gültige URL erstellen. Wenn mehrere Koordinaten weitergegeben werden, sind die zurückgegebenen Daten möglicherweise ungenauer, als wenn Sie Daten für Einzelkoordinaten anfordern. Wenn die Parameter „locations“ oder „path“ mehr als 512 Punkte oder Koordinaten enthalten, wird die Antwort INVALID_REQUEST zurückgegeben.

Antworten auf Höhendatenanfragen

  • Ein Array aus zwei oder mehr kommagetrennten Koordinaten-Strings, die durch einen senkrechten Strich (|) getrennt sind: path=40.714728,-73.998672|-34.397,150.644
  • Codierte Koordinaten mit dem Algorithmus für codierte Polylinien: path=enc:gfo}EtohhUxD@bAxJmGF

Koordinatenstrings für Breiten- und Längengrade werden mit Ziffern in einem kommagetrennten Textstring definiert. Beispiel: „40.714728,-73.998672|-34.397, 150.644“ ist ein gültiger path-Wert. Breiten- und Längengradwerte müssen einem gültigen Ort auf der Erde entsprechen. Breitengrade können einen beliebigen Wert zwischen -90 und 90 annehmen, während Längengrade einen beliebigen Wert zwischen -180 und -180 annehmen können. Wenn Sie einen ungültigen Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als ungültige Anfrage abgelehnt.

Sie können bis zu 512 Koordinaten in einem Array oder einer codierten Polylinie übergeben und trotzdem eine gültige URL erstellen. Wenn mehrere Koordinaten weitergegeben werden, sind die zurückgegebenen Daten möglicherweise ungenauer, als wenn Sie Daten für Einzelkoordinaten anfordern. Wenn die Parameter „locations“ oder „path“ mehr als 512 Punkte oder Koordinaten enthalten, wird die Antwort INVALID_REQUEST zurückgegeben.

Antworten auf Höhendatenanfragen

Für jede gültige Anfrage gibt der Elevation-Dienst eine Elevation-Antwort in dem Format zurück, das in der Anfrage-URL angegeben ist.

ElevationResponse

Feld Erforderlich Typ Beschreibung
required Array<ElevationResult> Weitere Informationen finden Sie unter ElevationResult.
required ElevationStatus Weitere Informationen finden Sie unter ElevationStatus.
optional String

Wenn der Dienst einen anderen Statuscode als OK zurückgibt, kann das Antwortobjekt ein zusätzliches error_message-Feld enthalten. Dieses Feld enthält detailliertere Informationen zu den Gründen für den angegebenen Statuscode. Dieses Feld wird nicht immer zurückgegeben und sein Inhalt kann sich ändern.

ElevationStatus

Vom Dienst zurückgegebene Statuscodes.

  • OK: Die API-Anfrage war erfolgreich.
  • DATA_NOT_AVAILABLE, die besagt, dass für die eingegebenen Orte keine Daten zur Verfügung stehen.
  • INVALID_REQUEST: Die API-Anfrage war falsch formatiert.
  • OVER_DAILY_LIMIT, der auf Folgendes hinweist:
    • Der API-Schlüssel fehlt oder ist ungültig.
    • Die Abrechnung wurde für Ihr Konto nicht aktiviert.
    • Das von Ihnen festgelegte Nutzungslimit wurde überschritten.
    • Die angegebene Zahlungsmethode ist nicht mehr gültig. Das kann z. B. bei einer abgelaufenen Kreditkarte der Fall sein.
  • OVER_QUERY_LIMIT: Der Anforderer hat das Kontingent überschritten.
  • REQUEST_DENIED: Die API hat die Anfrage nicht vollständig ausgeführt.
  • UNKNOWN_ERROR: Ein unbekannter Fehler ist aufgetreten.

Wenn der Statuscode nicht OK ist, enthält das Elevation-Antwortobjekt möglicherweise ein zusätzliches error_message-Feld. Dieses Feld enthält detailliertere Informationen zu den Gründen für den angegebenen Statuscode.

Die Antwort enthält ein results-Array mit den folgenden Elementen:

ElevationResult

Feld Erforderlich Typ Beschreibung
erforderlich Zahl

Die Höhe des Standorts in Metern.
required LatLngLiteral

Ein Standortelement für die Position, für die Höhendaten berechnet werden sollen. Bei Pfadanfragen enthält der Satz von location-Elementen die Punkte für die Höhenermittlung entlang des Pfades.

Weitere Informationen finden Sie unter LatLngLiteral.

optional Zahl

Der Wert, der in Metern die maximale Entfernung zwischen Datenpunkten anzeigt, von denen aus die Höhe interpoliert wurde. Falls die Auflösung nicht bekannt ist, fehlt dieses Attribut. Beachten Sie, dass Höhendaten ungenauer werden und somit größere Auflösungswerte haben, wenn mehrere Punkte übergeben werden. Um einen möglichst genauen Höhenwert für einen Punkt zu erhalten, sollte er einzeln abgefragt werden.

LatLngLiteral

Ein Objekt, das einen bestimmten Standort mit Breiten- und Längengrad in Dezimalgrad beschreibt.

Feld Erforderlich Typ Beschreibung
erforderlich Zahl

Breitengrad in Dezimalgrad
required Zahl

Längengrad in Dezimalgrad

Beispiele für Höhenangaben für bestimmte Positionen

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

URL

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034
    &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'

JSON

        
{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}

XML

        
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
</ElevationResponse>

Das folgende Beispiel zeigt mehrere Antworten (für Denver, CO, USA und Death Valley, CA, USA).

In dieser Anfrage wird das JSON-Flag output verwendet:

URL

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
    &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667&key=YOUR_API_KEY'

In dieser Anfrage wird das XML-Flag output verwendet:

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

Wählen Sie die Tabs unten aus, um die JSON- und XML-Beispielantworten aufzurufen.

JSON

      
{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
      {
        "elevation": -52.79492568969727,
        "location": { "lat": 36.455556, "lng": -116.866667 },
        "resolution": 19.08790397644043,
      },
    ],
  "status": "OK",
}

XML

      
<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>-52.7949257</elevation>
  <resolution>19.0879040</resolution>
 </result>
</ElevationResponse>

In den folgenden Beispielen werden Höhendaten entlang einer geraden Linie (path) vom Mount Whitney, Kalifornien, USA, nach Badwater, Kalifornien, USA, angefordert. Dies sind die höchsten und niedrigsten Punkte in den kontinentalen Vereinigten Staaten. Wir fragen nach drei samples, also den beiden Endpunkten und dem Mittelpunkt.

URL

https://maps.googleapis.com/maps/api/elevation/json
  ?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171
  &samples=3
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171&samples=3&key=YOUR_API_KEY'

JSON

      
{
  "results":
    [
      {
        "elevation": 4411.94189453125,
        "location": { "lat": 36.578581, "lng": -118.291994 },
        "resolution": 19.08790397644043,
      },
      {
        "elevation": 1372.8359375,
        "location": { "lat": 36.41150289067028, "lng": -117.5602607523847 },
        "resolution": 9.543951988220215,
      },
      {
        "elevation": -84.51690673828125,
        "location": { "lat": 36.23998, "lng": -116.83171 },
        "resolution": 9.543951988220215,
      },
    ],
  "status": "OK",
}

XML

      
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>36.5785810</lat>
   <lng>-118.2919940</lng>
  </location>
  <elevation>4411.9418945</elevation>
  <resolution>19.0879040</resolution>
 </result>
 <result>
  <location>
   <lat>36.4115029</lat>
   <lng>-117.5602608</lng>
  </location>
  <elevation>1372.8359375</elevation>
  <resolution>9.5439520</resolution>
 </result>
 <result>
  <location>
   <lat>36.2399800</lat>
   <lng>-116.8317100</lng>
  </location>
  <elevation>-84.5169067</elevation>
  <resolution>9.5439520</resolution>
 </result>
</ElevationResponse>