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 Parametersamples
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 Parametersamples
unterteilt das angegebenepath
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.
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.
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:
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'
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, 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
Über die Tabs unten kannst du dir die JSON- und XML-Beispielantworten ansehen.
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 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.
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>