Höhenanfragen und -antworten

Höhenanfragen

Anfragen an die Elevation API werden als URL-String erstellt. Die API gibt Höhendaten für Standorte auf der Erde zurück. Sie haben zwei Möglichkeiten, Standortdaten anzugeben:

  • Als eine Reihe von einem oder mehreren locations.
  • Als eine Reihe verbundener Punkte entlang eines path.

Bei beiden Ansätzen werden Breiten- und Längengradkoordinaten verwendet, um die Standorte oder Pfadeckpunkte zu identifizieren. In diesem Dokument wird 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. Bei Batch-Abfragen mit mehreren Standorten werden möglicherweise weniger genaue Daten zurückgegeben, insbesondere wenn die Standorte weit voneinander entfernt sind, da die Daten geglättet werden.

Eine Anfrage an die Elevation API hat folgendes Format:

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, die in einen <ElevationResponse> Knoten eingeschlossen ist.

Hinweis: URLs müssen ordnungsgemäß codiert sein, um gültig zu sein. Außerdem sind sie für alle Webdienste auf 16.384 Zeichen begrenzt. Beachten Sie dieses Limit, wenn Sie Ihre URLs erstellen. Unterschiedliche Browser, Proxys und Server können auch unterschiedliche Zeichenlimits für URLs haben.

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 Standorten geben Anfragen nach Höhendaten Daten zu den in der Anfrage übergebenen Standorten zurück. Bei Pfaden werden Höhendaten stattdessen entlang des angegebenen Pfads erhoben.

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

Alle Anfragen

  • key -- (erforderlich) Der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für die Kontingentverwaltung. Informationen zum Abrufen eines Schlüssels.

Positionsanfragen

  • locations (erforderlich) definiert die Standorte auf der Erde, für die Höhendaten zurückgegeben werden sollen. Dieser Parameter akzeptiert entweder einen einzelnen Standort als durch Kommas getrenntes Paar aus Breiten- und Längengrad (z.B. „40.714728,-73.998672“) oder mehrere Breiten-/Längengradpaare, 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 Höhendaten entlang von Pfaden

  • path (erforderlich) definiert einen Pfad auf der Erde, für den Höhendaten zurückgegeben werden sollen. Dieser Parameter definiert eine Reihe von mindestens zwei 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 ange101}geben.
  • samples (erforderlich) gibt die Anzahl der Beispielpunkte entlang eines Pfades an, für die Höhendaten zurückgegeben werden sollen. Der Parameter samples unterteilt den angegebenen path in eine geordnete Reihe von Punkten, die sich in gleichen Abständen entlang des Pfades befinden.

Standorte angeben

Positionsanfragen werden durch die Verwendung des Parameters locations angegeben. Sie geben Höhenanfragen für die bestimmten Standorte an, die als Breiten-/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 mit dem Algorithmus für codierte Polylinien: locations=enc:gfo}EtohhU

Koordinatenstrings für Breiten- und Längengrad werden mit Zahlen in einem durch Kommas getrennten Textstring definiert. Beispiel: „40.714728,-73.998672“ ist ein gültiger locations-Wert. Die Breiten- und Längengradwerte müssen einem gültigen Standort auf der Erde entsprechen. Breitengrade können einen beliebigen Wert zwischen -90 und 90 haben, während Längengrade einen beliebigen Wert zwischen -180 und 180 haben können. Wenn Sie einen ungültigen Breiten- oder Längengradwert angeben, wird Ihre Anfrage als fehlerhafte 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 Sie in den Parametern „locations“ oder „path“ mehr als 512 Punkte oder Koordinaten angeben, wird die Antwort INVALID_REQUEST zurückgegeben.

Pfade angeben

Anfragen für Höhendaten entlang von Pfaden werden durch die Verwendung der Parameter path und samples angegeben. Sie geben eine Anfrage für Höhendaten entlang eines Pfads in bestimmten Intervallen an. Wie bei Positionsanfragen mit dem Parameter locations wird mit dem Parameter path eine Reihe von Breiten- und Längengradwerten angegeben. Anders als bei Positionsanfragen wird mit dem Parameter path jedoch eine geordnete Reihe 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 entlang des gesamten Pfads verteilt sind, basierend auf der Anzahl der samples angegebenen (einschließlich der Endpunkte).

Der Parameter path kann eines der folgenden Argumente annehmen:

  • Ein Array aus mindestens zwei kommagetrennten Koordinatenstrings, 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ängengrad werden mit Zahlen in einem durch Kommas getrennten Textstring definiert. Beispiel: „40.714728,-73.998672|-34.397, 150.644“ ist ein gültiger path-Wert. Die Breiten- und Längengradwerte müssen einem gültigen Standort auf der Erde entsprechen. Breitengrade können einen beliebigen Wert zwischen -90 und 90 haben, während Längengrade einen beliebigen Wert zwischen -180 und 180 haben können. Wenn Sie einen ungültigen Breiten- oder Längengradwert angeben, wird Ihre Anfrage als fehlerhafte 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 Sie in den Parametern „locations“ oder „path“ mehr als 512 Punkte oder Koordinaten angeben, wird die Antwort INVALID_REQUEST zurückgegeben.

Antworten auf Höhenanfragen

  • Ein Array aus mindestens zwei kommagetrennten Koordinatenstrings, 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ängengrad werden mit Zahlen in einem durch Kommas getrennten Textstring definiert. Beispiel: „40.714728,-73.998672|-34.397, 150.644“ ist ein gültiger path-Wert. Die Breiten- und Längengradwerte müssen einem gültigen Standort auf der Erde entsprechen. Breitengrade können einen beliebigen Wert zwischen -90 und 90 haben, während Längengrade einen beliebigen Wert zwischen -180 und -180 haben können. Wenn Sie einen ungültigen Breiten- oder Längengradwert angeben, wird Ihre Anfrage als fehlerhafte 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 Sie in den Parametern „locations“ oder „path“ mehr als 512 Punkte oder Koordinaten angeben, wird die Antwort INVALID_REQUEST zurückgegeben.

Antworten auf Höhenanfragen

Für jede gültige Anfrage gibt der Elevation-Dienst eine Höhenantwort im Format zurück, das in der Anfrage-URL angegeben ist.

ElevationResponse

Feld Erforderlich Typ Beschreibung
erforderlich Array<ElevationResult> Weitere Informationen finden Sie unter ElevationResult.
erforderlich 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 Feld error_message 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

Statuscodes, die vom Dienst zurückgegeben werden.

  • OK gibt an, dass die API-Anfrage erfolgreich war.
  • DATA_NOT_AVAILABLE gibt an, dass für die eingegebenen Standorte keine Daten verfügbar sind.
  • INVALID_REQUEST gibt an, dass die API-Anfrage fehlerhaft war.
  • OVER_DAILY_LIMIT gibt einen der folgenden Fälle an:
    • Der API-Schlüssel fehlt oder ist ungültig.
    • Die Abrechnung ist 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 gibt an, dass der Anfragende das Kontingent überschritten hat.
  • REQUEST_DENIED gibt an, dass die API die Anfrage nicht abgeschlossen hat.
  • UNKNOWN_ERROR gibt einen unbekannten Fehler an.

Wenn der Statuscode nicht OK ist, kann das Elevation-Antwortobjekt ein zusätzliches Feld error_message enthalten. 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.
erforderlich LatLngLiteral

Ein Standort-Element der Position, für die Höhendaten berechnet werden sollen. Bei Pfadanfragen enthält die Reihe von Standort-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 angibt, 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 im Dezimalformat beschreibt.

Feld Erforderlich Typ Beschreibung
erforderlich Zahl

Breitengrad im Dezimalformat
erforderlich Zahl

Längengrad im Dezimalformat

Beispiele für Positionsanfragen

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, Colorado, und für Death Valley, Kalifornien).

Diese Anfrage zeigt die Verwendung des JSON-Flags output:

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'

Diese Anfrage zeigt die Verwendung des XML-Flags output:

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

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

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 eines geraden path von Mount Whitney, Kalifornien, nach Badwater, Kalifornien, dem höchsten und niedrigsten Punkt der kontinentalen Vereinigten Staaten, angefordert. Wir fordern drei samples an, sodass die beiden Endpunkte und der Mittelpunkt enthalten sind.

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>