Höhenanfragen und -antworten

Höhenanfragen

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 ein oder mehrere 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 Batchabfragen 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 Elevation API-Anfrage weist die folgende Form auf:

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

Dabei kann outputFormat einen der folgenden Werte haben:

• json (empfohlen) verweist auf eine Ausgabe in JavaScript Object Notation (JSON).
• xml: Gibt die Ausgabe in XML an, die in einem <ElevationResponse>-Knoten eingehüllt ist.

Hinweis: URLs müssen richtig codiert sein, um gültig zu sein. Außerdem sind sie für alle Webdienste auf 16.384 Zeichen beschränkt. Berücksichtigen Sie diese Beschränkung beim Erstellen Ihrer URLs. Auch für unterschiedliche Browser, Proxys und Server können unterschiedliche Zeichenbeschränkungen für URLs gelten.

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 einen geordneten Pfad gilt. Für einzelne Standorte werden bei Höhenanfragen Daten zu den spezifischen Standorten zurückgegeben, die in der Anfrage übergeben wurden. Bei Pfaden werden stattdessen Stichproben für Höhenanfragen des angegebenen Pfads verwendet.

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

Alle Anfragen

• key (erforderlich): Der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel kennzeichnet Ihre Anwendung zum Zweck der Kontingentverwaltung. Weitere Informationen zum Abrufen eines Schlüssels

Standortanfragen

• locations (erforderlich): definiert die Standorte auf der Erde, für die Höhendaten zurückgegeben werden sollen. Dieser Parameter kann entweder einen einzelnen Standort als kommagetrenntes Paar {latitude,longitude} (z. B. „40.714728,-73.998672“) oder mehrere Breiten-/Längengradpaare als Array oder als codierte Polylinie annehmen. Für diesen Parameter gilt ein Limit von 512 Punkten. Weitere Informationen finden Sie unten im Abschnitt Standorte angeben.

Anfragen für Stichprobendaten entlang von Pfaden

• 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 {Breitengrad,Längengrad}-Paaren, die einen Pfad auf der Erdoberfläche definieren. Dieser Parameter muss in Verbindung mit dem unten beschriebenen Parameter samples verwendet werden. Für diesen Parameter gilt eine Beschränkung 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

Positionsabfragen werden mit dem Parameter locations angegeben. Dabei werden Höhenanfragen für die jeweiligen Standorte als Breiten-/Längengradwerte übergeben.

Der Parameter locations kann die folgenden Argumente annehmen:

• Eine einzelne Koordinate: locations=40.714728,-73.998672
• Ein Array von Koordinaten, die durch ein Pipe-Zeichen (|) voneinander getrennt sind: locations=40.714728,-73.998672|-34.397,150.644
• Einen Satz codierter Koordinaten, die mithilfe des Algorithmus für codierte Polylinien codiert wurden: locations=enc:gfo}EtohhU

Breiten- und Längengradkoordinaten werden mithilfe von Ziffern in einem durch Kommas getrennten Textstring definiert. „40.714728,-73.998672“ ist beispielsweise 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 jeden Wert zwischen -90 und 90 haben, während Längengrade jeden Wert zwischen -180 und 180 haben können. Wenn Sie einen ungültigen Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als fehlerhaft abgelehnt.

Sie können in einem Array oder einem codierten Polyline bis zu 512 Koordinaten übergeben und trotzdem eine gültige URL erstellen. Wenn mehrere Koordinaten übergeben werden, sind die zurückgegebenen Daten möglicherweise ungenauer, als wenn Sie Daten für Einzelkoordinaten anfordern. Bei Überschreiten von 512 Punkten oder Koordinaten in den Parametern „locations“ oder „path“ wird eine INVALID_REQUEST-Antwort zurückgegeben.

Pfade angeben

Anfragen für Stichprobenpfade werden mit den Parametern path und samples angegeben. Sie geben an, dass in bestimmten Intervallen Höhendaten entlang eines Pfades angefordert werden. Wie bei Positionsanfragen mit dem Parameter locations gibt der Parameter path einen Satz von Breiten- und Längengradwerten an. Anders als bei Positionsanfragen wird mit dem path-Parameter jedoch ein geordneter Satz von Eckpunkten angegeben. Es werden aber keine Höhendaten 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.

Der Parameter path kann eines der folgenden Argumente annehmen:

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

Breiten- und Längengradkoordinaten werden mithilfe von Ziffern in einem durch Kommas getrennten Textstring definiert. "40.714728,-73.998672|-34.397, 150.644" ist beispielsweise ein gültiger Wert für path. Breiten- und Längengradwerte müssen einem gültigen Standort auf der Erdoberfläche entsprechen. Für den Breitengrad können alle Werte zwischen -90 und 90 und für den Längengrad beliebige Werte zwischen -180 und 180 angegeben werden. Wenn Sie einen ungültigen Breiten- oder Längengrad angeben, wird Ihre Anfrage als fehlerhafte Anfrage abgelehnt.

Sie können in einem Array oder einer codierten Polylinie bis zu 512 Koordinaten übergeben, während Sie gleichzeitig eine gültige URL erstellen. Beachten Sie, dass beim Übergeben mehrerer Koordinaten die Genauigkeit der zurückgegebenen Daten eine geringere Auflösung aufweisen kann, als wenn Sie Daten für eine einzelne Koordinate anfordern. Bei Überschreiten von 512 Punkten oder Koordinaten in den Parametern „locations“ oder „path“ wird eine INVALID_REQUEST-Antwort zurückgegeben.

Antworten für die Höhe

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

Wenn der Statuscode nicht OK ist, kann es im Antwortobjekt „Elevation“ ein zusätzliches Feld vom Typ error_message geben. 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:

Das location-Objekt hat die folgenden Elemente:

Beispiele für Positionshöhen

Im folgenden Beispiel wird die Höhe von Denver, Colorado, im JSON-Format 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 Death Valley, CA).

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

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

Wählen Sie die Tabs unten aus, um die Beispiel-JSON- und -XML-Antworten 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 Liniepath von Mt. Whitney, CA, zum Badwater, CA, angefordert, dem höchsten und dem niedrigsten Punkt auf dem nordamerikanischen Festland. Wir benötigen 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>