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 Satz aus 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 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 werden möglicherweise Daten mit einer geringeren Genauigkeit zurückgegeben. Dies ist vor allem dann wichtig, wenn die Standorte verteilt sind, da eine Datenglättung auftritt.
Eine Elevation API-Anfrage weist die folgende Form auf:
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 eine Ausgabe in XML an, eingebettet in einen<ElevationResponse>
-Knoten.
Hinweis: URLs müssen richtig codiert sein, um gültig zu sein, und dürfen für alle Webdienste auf 16.384 Zeichen beschränkt sein. 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 bei allen URLs üblich, werden die Parameter durch ein Et-Zeichen (&
) getrennt. Die Liste der Parameter und ihre möglichen Werte finden Sie unten.
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. Bei diesem Parameter wird entweder ein einzelner Standort als kommagetrenntes {Breitengrad,Längengrad}-Paar (z.B. "40.714728,-73.998672") oder mehrere Breiten-/Längengradpaare verwendet, die als Array oder als codierte Polylinie übergeben werden. Für diesen Parameter gibt es eine Beschränkung 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 Parametersamples
verwendet werden. Für diesen Parameter gilt eine Beschränkung 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 Parametersamples
unterteilt den angegebenenpath
in einen geordneten Satz von abstandsgetreuen Punkten entlang des Pfads.
Standorte angeben
Positionsanfragen werden mithilfe des Parameters locations
angegeben, der Höhenanfragen für bestimmte Standorte angibt, 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 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. 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 Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als fehlerhaft 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 beim Anfordern von Daten für eine einzelne Koordinate.
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 Stichprobendaten entlang von Pfaden werden mithilfe der Parameter path
und samples
angegeben, die eine Anfrage nach Höhendaten entlang eines Pfads mit festgelegten Intervallen definieren. Wie bei Positionsanfragen mit dem Parameter locations
gibt der Parameter path
einen Satz von Breiten- und Längengradwerten an. Anders als bei Positionsanfragen gibt der path
jedoch einen geordneten Satz von Eckpunkten an. Die Höhendaten werden nicht nur für die Eckpunkte zurückgegeben, sondern entlang des Pfads stichprobenartig abgefragt, 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 kommagetrennten Koordinaten in Form von Textstrings, die durch ein Pipe-Zeichen (
|
) voneinander 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 Wert für den Breiten- oder Längengrad angeben, wird Ihre Anfrage als fehlerhaft 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 beim Anfordern von Daten für eine einzelne Koordinate. 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 in dem Format zurück, das in der Anfrage-URL angegeben ist.
ElevationResponse
Field | Required | Type | Description |
---|---|---|---|
| required | Array<ElevationResult> | See ElevationResult for more information. |
| required | ElevationStatus | See ElevationStatus for more information. |
| optional | string |
When the service returns a status code other than |
ElevationStatus
Status codes returned by service.
OK
indicating the API request was successful.DATA_NOT_AVAILABLE
indicating that there's no available data for the input locations.INVALID_REQUEST
indicating the API request was malformed.OVER_DAILY_LIMIT
indicating any of the following:- The API key is missing or invalid.
- Billing has not been enabled on your account.
- A self-imposed usage cap has been exceeded.
- The provided method of payment is no longer valid (for example, a credit card has expired).
OVER_QUERY_LIMIT
indicating the requestor has exceeded quota.REQUEST_DENIED
indicating the API did not complete the request.UNKNOWN_ERROR
indicating an unknown error.
Ist der Statuscode nicht OK
, ist im Elevation-Antwortobjekt möglicherweise ein zusätzliches Feld error_message
vorhanden. 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
Field | Required | Type | Description |
---|---|---|---|
| required | number | The elevation of the location in meters. |
| required | LatLngLiteral | A location element of the position for which elevation data is being computed. Note that for path requests, the set of location elements will contain the sampled points along the path. See LatLngLiteral for more information. |
| optional | number | The value indicating the maximum distance between data points from which the elevation was interpolated, in meters. This property will be missing if the resolution is not known. Note that elevation data becomes more coarse (larger resolution values) when multiple points are passed. To obtain the most accurate elevation value for a point, it should be queried independently. |
Das location
-Objekt hat die folgenden Elemente:
LatLngLiteral
An object describing a specific location with Latitude and Longitude in decimal degrees.
Field | Required | Type | Description |
---|---|---|---|
| required | number | Latitude in decimal degrees |
| required | number | Longitude in decimal degrees |
Beispiele für Positionshöhen
Im folgenden Beispiel wird die Höhe für Denver, Colorado, die „Mile High City“ im JSON-Format 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'
JavaScript Object Notation
{ "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, und für Death Valley, CA).
In dieser Anfrage wird die Verwendung des JSON-Flags output
veranschaulicht:
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 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 sich die JSON- und XML-Beispielantworten anzusehen.
JavaScript Object Notation
{ "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 geradlinigen Linie (path
) von Mt. Whitney (Kalifornien) nach Badwater (Kalifornien) angefordert, dem höchsten und niedrigsten Punkt der Kontinentalstaaten der USA. Es werden drei samples
angefordert, sodass die beiden Endpunkte und der Halbpunkt 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'
JavaScript Object Notation
{ "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>