Richieste di altitudine
Le richieste API Elevation vengono create come una stringa URL. L'API restituisce i dati di altitudine dei luoghi della Terra. Puoi specificare i dati sulla posizione in uno di due modi:
- Come insieme di uno o più
locations
. - Come una serie di punti collegati lungo un
path
.
Entrambi questi approcci utilizzano le coordinate di latitudine/longitudine per identificare le posizioni o i vertici del percorso. Questo documento descrive il formato richiesto degli URL dell'API Elevation e i parametri disponibili.
L'API Elevation restituisce i dati per le query a punto singolo con la massima precisione possibile. Le query batch che coinvolgono più località potrebbero restituire dati con minore precisione, soprattutto se le località sono disseminate poiché i dati vengono semplificati.
Una richiesta all'API Elevation ha il seguente formato:
https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters
dove outputFormat
può essere uno dei seguenti valori:
json
(consigliato) indica l'output in JavaScript Object Notation (JSON); oppurexml
, indica l'output in XML, con wrapping all'interno di un nodo<ElevationResponse>
.
Nota: gli URL devono essere codificati correttamente per essere validi e avere un limite di 16.384 caratteri per tutti i servizi web. Tieni presente questo limite quando crei gli URL. Tieni presente che anche browser, proxy e server diversi possono avere limiti di caratteri per gli URL diversi.
HTTPS è obbligatorio per le richieste che utilizzano una chiave API.
Parametri della richiesta
Le richieste all'API Elevation utilizzano parametri diversi a seconda che siano riferite a località discrete o a un percorso ordinato. Per le località discrete, le richieste di dati sull'altitudine per le località specifiche trasmesse nella richiesta; per i percorsi, le richieste di altitudine vengono invece campionate lungo il percorso specificato.
Come standard per tutti gli URL, i parametri vengono separati
utilizzando la e commerciale (&
). Di seguito sono riportati l'elenco dei parametri
e i relativi valori possibili.
Tutte le richieste
key
: (obbligatorio) la chiave API dell'applicazione. Questa chiave identifica l'applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.
Richieste posizionali
locations
(obbligatorio) definisce le località della Terra da cui restituire i dati di altitudine. Questo parametro prende una singola posizione come coppia {latitudine,longitudine} separate da virgole (ad es. "40.714728,-73.998672") o più coppie di latitudine/longitudine trasmesse come array o come polilinea codificata. Esiste un limite di 512 punti per questo parametro specifico. Per ulteriori informazioni, consulta la sezione Specifica delle località di seguito.
Richieste di percorso campionato
path
(obbligatorio) definisce un percorso sulla Terra per il quale restituire i dati di altitudine. Questo parametro definisce un insieme di due o più coppie ordinate di {latitudine,longitudine} che definiscono un percorso lungo la superficie della Terra. Questo parametro deve essere utilizzato in combinazione con il parametrosamples
descritto di seguito. Esiste un limite di 512 punti per questo parametro specifico. Per ulteriori informazioni, consulta la sezione Specifica dei percorsi di seguito.samples
(obbligatorio) specifica il numero di punti di esempio lungo un percorso per il quale restituire dati di altitudine. Il parametrosamples
divide il valorepath
specificato in un insieme ordinato di punti equidistanti lungo il percorso.
Specifica delle località
Le richieste di posizione vengono indicate mediante l'uso del parametro locations
, che indica le richieste di altitudine per le località specifiche trasmesse come valori di latitudine/longitudine.
Il parametro locations
può assumere i seguenti
argomenti:
- Una singola coordinata:
locations=40.714728,-73.998672
- Un array di coordinate separate dal carattere barra verticale ("
|
"):locations=40.714728,-73.998672|-34.397,150.644
- Un set di coordinate codificate utilizzando l'algoritmo Polilinea codificata:
locations=enc:gfo}EtohhU
Le stringhe con coordinate di latitudine e longitudine sono definite utilizzando numeri all'interno di una stringa di testo separata da virgole. Ad esempio, "40.714728,-73.998672"
è un valore locations
valido. I valori di latitudine e longitudine devono corrispondere a una posizione valida sulla superficie della Terra. La latitudine può assumere qualsiasi valore compreso tra -90
e 90
, mentre i valori di longitudine possono avere qualsiasi valore compreso tra -180
e 180
. Se specifichi un valore non valido per la latitudine o la longitudine, la richiesta verrà rifiutata.
Puoi passare fino a 512 coordinate all'interno di un array o di una polilinea codificata, pur generando un URL valido.
Tieni presente che quando passi più coordinate, l'accuratezza dei dati restituiti potrebbe essere inferiore rispetto a quando vengono richiesti i dati per una singola coordinata.
Il superamento di 512 punti o coordinate nei parametri "locations" o "path" restituisce una risposta INVALID_REQUEST
.
Specifica dei percorsi
Le richieste di percorso campionate vengono indicate mediante l'uso dei parametri path
e samples
, indicando una richiesta di dati di altitudine lungo un percorso a intervalli specificati. Come per le richieste di posizione che utilizzano il parametro locations
, il parametro path
specifica un insieme di valori di latitudine e longitudine. Tuttavia, a differenza di una richiesta di posizione, path
specifica un insieme ordinato di vertici. Anziché restituire i dati di elevazione solo ai vertici, le richieste di percorso vengono campionate lungo la lunghezza del percorso, in base al numero di samples
specificato (inclusi gli endpoint).
Il parametro path
può assumere uno dei seguenti
argomenti:
- Un array di due o più stringhe di testo con coordinate separate da virgole separate dalla barra verticale ("
|
"):path=40.714728,-73.998672|-34.397,150.644
- Coordinate codificate utilizzando l'algoritmo di polilinea codificata:
path=enc:gfo}EtohhUxD@bAxJmGF
Le stringhe con coordinate di latitudine e longitudine sono definite utilizzando numeri all'interno di una stringa di testo separata da virgole. Ad esempio,
"40.714728,-73.998672|-34.397, 150.644" è un valore
path
valido. I valori di latitudine e longitudine devono corrispondere
a una posizione valida sulla faccia della Terra. La latitudine può assumere qualsiasi valore compreso tra -90
e 90
, mentre i valori di longitudine possono avere qualsiasi valore compreso tra -180
e 180
. Se specifichi un valore non valido per la latitudine o la longitudine, la richiesta verrà rifiutata.
Puoi passare fino a 512 coordinate all'interno di un array o di una polilinea codificata, pur generando un URL valido. Tieni presente che quando trasmetti più
coordinate, l'accuratezza dei dati restituiti potrebbe avere una risoluzione inferiore rispetto
alla richiesta dei dati per una singola coordinata. Il superamento di 512 punti o coordinate nei parametri "locations" o "path" restituisce una risposta INVALID_REQUEST
.
Risposte altitudine
Per ogni richiesta valida, il servizio Altitudine restituirà una risposta nel formato indicato nell'URL della richiesta.
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.
Quando il codice di stato è diverso da OK
, potrebbe essere presente un campo error_message
aggiuntivo all'interno dell'oggetto Risposta Elevation. Questo campo contiene informazioni più dettagliate sui motivi alla base del codice di stato specificato.
La risposta contiene un array results
con i seguenti elementi:
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. |
L'oggetto location
contiene i seguenti elementi:
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 |
Esempi di elevazione posizionale
L'esempio seguente richiede l'elevazione per Denver, in Colorado, "Mile High City" in formato JSON:
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>
L'esempio seguente mostra più risposte (per Denver, CO e Death Valley, CA).
Questa richiesta mostra l'uso del flag JSON output
:
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'
Questa richiesta dimostra che si utilizza il flag XML output
:
https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY
Seleziona le schede qui sotto per visualizzare le risposte JSON e XML di esempio.
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>
I seguenti esempi richiedono dati di altitudine lungo una linea retta path
da Mt. Whitney, CA, a Badwater, California, dai punti più alti e più bassi degli Stati Uniti continentali. Chiediamo tre
samples
, in modo da includere i due endpoint e il
punto a metà.
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>