Höhenanfragen und -antworten

Höhendatenanfragen

Elevation API-Anfragen 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 Gruppe mit einem oder mehreren locations.
• Als Reihe verbundener Punkte entlang einer path.

Bei beiden Ansätzen werden Breiten- und Längengradkoordinaten verwendet, um die Orte oder Pfadknoten 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 Daten mit geringerer Genauigkeit zurückgegeben, insbesondere wenn die Standorte weit voneinander entfernt sind, da die Daten geglättet werden.

Eine Anfrage an die Elevation API hat das folgende 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.
• xml: Gibt die Ausgabe in XML an, die in einem <ElevationResponse>-Knoten umschlossen ist.

Hinweis: URLs müssen richtig codiert sein, damit sie gültig sind. Außerdem sind sie für alle Webdienste auf 16.384 Zeichen beschränkt. Beachten Sie dieses Limit beim Erstellen Ihrer URLs. Unterschiedliche Browser, Proxys und Server können auch unterschiedliche Zeichenlimits für URLs haben.

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

Anfrageparameter

Für Anfragen an die Elevation API werden unterschiedliche Parameter verwendet, je nachdem, ob die Anfrage für einzelne Standorte oder für einen geordneten Pfad gilt. Bei einzelnen Standorten werden bei Höhendatenanfragen Daten zu den in der Anfrage übergebenen Standorten zurückgegeben. Bei Pfaden werden Höhendatenanfragen stattdessen entlang des angegebenen Pfads erhoben.

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

Alle Anfragen

• key – (erforderlich) Der API-Schlüssel Ihrer Anwendung. Mit diesem Schlüssel wird Ihre Anwendung für die Kontingentverwaltung identifiziert. 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 Stichprobenpfade

• path (erforderlich): definiert einen Pfad auf der Erde, für den Höhendaten zurückgegeben werden sollen. Mit diesem Parameter wird ein Satz von mindestens zwei geordneten Paaren aus Breiten- und Längengrad definiert,die einen Pfad entlang der Erdoberfläche darstellen. 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 Parameter samples unterteilt den angegebenen path in eine geordnete Menge von Punkten, die sich in gleichen Abständen entlang des Pfades befinden.

Standorte angeben

Positionsanfragen werden durch die Verwendung des Parameters locations angegeben. Dieser gibt Höhenanfragen für die als Breiten-/Längengradwerte übergebenen Standorte an.

Der Parameter locations kann die folgenden Argumente annehmen:

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

Koordinatenstrings für Breiten- und Längengrad werden mit Ziffern 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 Erdoberfläche entsprechen. Breitengradkoordinaten können einen beliebigen Wert zwischen -90 und 90 annehmen, während Längengradkoordinaten einen beliebigen Wert zwischen -180 und 180 annehmen können. Wenn Sie einen ungültigen Breitengrad- 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 eine INVALID_REQUEST-Antwort zurückgegeben.

Pfade angeben

Anfragen für Stichprobenpfade werden durch die Verwendung der Parameter path und samples angegeben. Sie weisen auf eine Anfrage für Höhendaten entlang eines Pfads in angegebenen Intervallen hin. 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, basierend auf der Anzahl der angegebenen samples, einschließlich der Endpunkte.

Der Parameter path kann eines der folgenden Argumente annehmen:

• Ein Array aus zwei oder mehr durch Kommas getrennten Koordinaten-Textstrings, die durch den 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 Ziffern 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 Ort auf der Erdoberfläche entsprechen. Breitengradwerte können einen beliebigen Wert zwischen -90 und 90 annehmen, während Längengradwerte einen beliebigen Wert zwischen -180 und 180 annehmen können. Wenn Sie einen ungültigen Breitengrad- 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 eine INVALID_REQUEST-Antwort zurückgegeben.

Antworten auf Höhendatenanfragen

• Ein Array aus zwei oder mehr durch Kommas getrennten Koordinaten-Textstrings, die durch den 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 Ziffern 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 Ort auf der Erdoberfläche entsprechen. Breitengradkoordinaten können einen beliebigen Wert zwischen -90 und 90 annehmen, während Längengradkoordinaten einen beliebigen Wert zwischen -180 und -180 annehmen können. Wenn Sie einen ungültigen Breitengrad- 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 eine INVALID_REQUEST-Antwort zurückgegeben.

Antworten auf Höhendatenanfragen

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

ElevationResponse

ElevationStatus

Statuscodes, die vom Dienst zurückgegeben werden.

• OK: Die API-Anfrage war erfolgreich.
• DATA_NOT_AVAILABLE gibt an, dass für die eingegebenen Orte keine Daten verfügbar sind.
• INVALID_REQUEST: Die API-Anfrage war falsch formatiert.
• OVER_DAILY_LIMIT, die Folgendes angibt:
  • 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, kann im Höhenantwortobjekt ein zusätzliches Feld error_message vorhanden sein. 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

LatLngLiteral

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

Beispiele für die Positionsangabe der Höhe

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

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

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

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

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

In dieser Anfrage wird das JSON-Flag output verwendet:

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

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.

      
{
  "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",
}
      
      

      
<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 in Kalifornien bis nach Badwater in Kalifornien angefordert, den höchsten und niedrigsten Punkten auf dem Festland der USA. Wir bitten um drei samples, also die beiden Endpunkte und den Mittelpunkt.

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 -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'
    

      
{
  "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",
}
      
      

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