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. Es gibt zwei Möglichkeiten, Standortdaten anzugeben:

• Als Satz aus einem oder mehreren locations.
• als eine Reihe verbundener Punkte entlang eines path-Elements.

Bei beiden Ansätzen werden Breiten-/Längengradkoordinaten verwendet, um die Standorte oder Pfadeckpunkte zu identifizieren. In diesem Dokument werden das erforderliche Format der 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 können Daten mit einer geringeren Genauigkeit zurückgegeben werden, insbesondere wenn die Standorte verteilt sind, da eine gewisse Glättung der Daten erfolgt.

Eine Elevation API-Anfrage hat die folgende Form:

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

Dabei kann outputFormat einer der folgenden Werte sein:

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

Hinweis: URLs müssen richtig codiert sein, um gültig zu sein. Sie dürfen für alle Webdienste maximal 16.384 Zeichen umfassen. Beachten Sie diese Beschränkung beim Erstellen der URLs. Beachten Sie, dass unterschiedliche Browser, Proxys und Server ebenfalls 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 sie sich auf einzelne Standorte oder einen Pfad beziehen. Bei einzelnen Standorten werden bei Höhenanfragen Daten zu den spezifischen Standorten zurückgegeben, die in der Anfrage übergeben wurden. Bei Pfaden werden stattdessen Stichproben entlang des angegebenen Pfads ermittelt.

Wie bei allen URLs üblich, werden die Parameter durch kaufmännische Und-Zeichen (&) voneinander getrennt. Die Parameter und ihre möglichen Werte sind unten aufgeführt.

Alle Anträge

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

Positionsanfragen

• locations (erforderlich) definiert die Standorte auf der Erde, für die Höhendaten zurückgegeben werden sollen. Für diesen Parameter wird entweder ein einzelner Standort als durch Kommas getrenntes {Breitengrad,Längengrad}-Paar (z.B. „40.714728,-73.998672“) oder mehrere Paare aus Breiten- und Längengrad als Array oder codierte Polylinie übergeben. 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 eine Gruppe 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 ein Limit von 512 Punkten. Weitere Informationen finden Sie unten im Abschnitt Pfade angeben.
• samples (erforderlich) gibt die Anzahl der Beispielpunkte entlang eines Pfads an, für die Höhendaten zurückgegeben werden sollen. Der Parameter samples unterteilt das angegebene path in einen geordneten Satz von abstandsgetreuen Punkten entlang des Pfads.

Standorte angeben

Positionsanfragen werden mithilfe des Parameters locations angegeben, der Höhendatenanfragen für bestimmte Standorte definiert, 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 ein Pipe-Zeichen (|) getrennt sind: locations=40.714728,-73.998672|-34.397,150.644
• Eine Reihe codierter Koordinaten unter Verwendung des Algorithmus für codierte Polylinien: locations=enc:gfo}EtohhU

Breiten- und Längengradkoordinaten werden durch Ziffern in einem durch Kommas getrennten Textstring definiert. „40.714728,-73.998672“ ist beispielsweise ein gültiger locations-Wert. Die 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 alle Werte zwischen -180 und 180 angegeben werden. Wenn Sie einen ungültigen Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als ungültige Anfrage abgelehnt.

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

Pfade angeben

Anfragen für Stichprobendaten entlang von Pfaden werden mithilfe der Parameter path und samples angegeben, die eine Anfrage für Höhendaten entlang eines Pfads in festgelegten Intervallen angeben. Wie bei Positionsanfragen mit dem Parameter locations gibt der Parameter path eine Reihe von Breiten- und Längengradwerten an. Anders als bei Positionsanfragen gibt path jedoch einen geordneten Satz von Eckpunkten an. Die Höhendaten werden nicht nur für die Eckpunkte zurückgegeben. Stattdessen werden Pfadanfragen entlang des Pfads stichprobenartig abgefragt, basierend auf der Anzahl der angegebenen samples (einschließlich der Endpunkte).

Der Parameter path kann eines der folgenden Argumente enthalten:

• Ein Array von zwei oder mehr durch Kommas getrennten Koordinatentextstrings, die durch ein Pipe-Zeichen (|) voneinander getrennt sind: path=40.714728,-73.998672|-34.397,150.644
• Codierte Koordinaten unter Verwendung des Algorithmus für codierte Polylinien: path=enc:gfo}EtohhUxD@bAxJmGF

Breiten- und Längengradkoordinaten werden durch Ziffern in einem durch Kommas getrennten Textstring definiert. "40.714728,-73.998672|-34.397, 150.644" ist beispielsweise ein gültiger path-Wert. Die 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 alle Werte zwischen -180 und 180 angegeben werden. Wenn Sie einen ungültigen Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als ungültige Anfrage abgelehnt.

In einem Array oder einer codierten Polylinie können bis zu 512 Koordinaten übergeben werden, während eine gültige URL erstellt wird. Beachten Sie, dass beim Übergeben mehrerer Koordinaten die Genauigkeit der zurückgegebenen Daten eine geringere Auflösung sein kann als beim Anfordern von Daten für eine einzelne Koordinate. Bei mehr als 512 Punkten oder Koordinaten in den Parametern „locations“ oder „path“ wird eine INVALID_REQUEST-Antwort 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.

Lautet der Statuscode nicht OK, enthält das Höhen-Antwortobjekt möglicherweise das zusätzliche Feld error_message. 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 für Denver, Colorado, die „Mile High City“ 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 für 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

Über die Tabs unten kannst du dir die JSON- und XML-Beispielantworten ansehen.

{
  "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 von Mt. Whitney, CA, USA, nach Badwater, CA, den höchsten und niedrigsten Punkten der kontinentalen USA angefordert. Es werden drei samples angefordert, das heißt, dies umfasst die beiden Endpunkte und die Hälfte der Strecke.

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>