Richieste di altitudine e risposte

Richieste di riassegnazione

Le richieste all'API Elevation vengono create come stringa URL. L'API restituisce i dati sull'altitudine per le località della Terra. Puoi specificare i dati sulla posizione in uno dei seguenti 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 località 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 su un singolo punto con la massima accuratezza possibile. Le query in batch che coinvolgono più località potrebbero restituire dati con una precisione inferiore, soprattutto se le località sono distanti tra loro, poiché i dati vengono in qualche modo smussati.

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); oppure
  • xml, indica l'output in XML, racchiuso in un nodo <ElevationResponse>.

Nota: gli URL devono essere codificati correttamente per essere validi e sono limitati a 16.384 caratteri per tutti i servizi web. Tieni presente questo limite quando crei gli URL. Tieni presente che browser, proxy e server diversi possono avere limiti di caratteri degli URL diversi.

HTTPS è obbligatorio per le richieste che utilizzano una chiave API.

Parametri di richiesta

Le richieste all'API Elevation utilizzano parametri diversi a seconda che la richiesta riguardi località distinte o un percorso ordinato. Per le località discrete, le richieste di altitudine restituiscono dati sulle località specifiche passate nella richiesta; per i percorsi, le richieste di altitudine vengono invece campionate lungo il percorso specificato.

Come avviene di norma in tutti gli URL, i parametri sono separati utilizzando il carattere e commerciale (&amp;). L'elenco dei parametri e dei relativi valori possibili è riportato di seguito.

Tutte le richieste

  • key - (obbligatorio) La chiave API della tua applicazione. Questa chiave identifica la tua applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.

Richieste di posizione

  • locations (obbligatorio) definisce le località sulla Terra da cui restituire i dati sull'altitudine. Questo parametro accetta una singola località come coppia {latitude,longitude} separata da virgole (ad es. "40.714728,-73.998672") o più coppie di latitudine/longitudine passate come array o come polilinea codificata. Per questo parametro specifico esiste un limite di 512 punti. Per saperne di più, consulta Specifica le località di seguito.

Richieste di percorsi campionati

  • path (obbligatorio) definisce un percorso sulla Terra per il quale restituire i dati sull'altitudine. Questo parametro definisce un insieme di due o più coppie {latitudine,longitudine} ordinate che definiscono un percorso lungo la superficie della Terra. Questo parametro deve essere utilizzato insieme al parametro samples descritto di seguito. Per questo parametro specifico esiste un limite di 512 punti. Per saperne di più, consulta la sezione Specifica i percorsi di seguito.
  • samples (obbligatorio) specifica il numero di punti di campionamento lungo un percorso per i quali restituire i dati sull'altitudine. Il parametro samples divide il path specificato in un insieme ordinato di punti equidistanti lungo il percorso.

Specifica le località

Le richieste di posizione sono indicate tramite l'utilizzo del parametro locations, che indica le richieste di altitudine per le località specifiche passate come valori di latitudine/longitudine.

Il parametro locations può accettare i seguenti argomenti:

  • Una singola coordinata: locations=40.714728,-73.998672
  • Un array di coordinate separate utilizzando il carattere barra verticale ("|"): locations=40.714728,-73.998672|-34.397,150.644
  • Un insieme di coordinate codificate utilizzando l'algoritmo di polilinea codificata: locations=enc:gfo}EtohhU

Le stringhe di coordinate di latitudine e longitudine vengono 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 località valida sulla superficie terrestre. Le latitudini possono assumere qualsiasi valore compreso tra -90 e 90, mentre i valori di longitudine possono assumere qualsiasi valore compreso tra -180 e 180. Se specifichi un valore di latitudine o longitudine non valido, la richiesta verrà rifiutata come richiesta non valida.

Puoi passare fino a 512 coordinate all'interno di un array o di una polilinea codificata, creando comunque un URL valido. Tieni presente che, quando passi più coordinate, l'accuratezza dei dati restituiti potrebbe avere una risoluzione inferiore rispetto a quando richiedi i dati per una singola coordinata. Se superi i 512 punti o coordinate nei parametri "locations" o "path", viene restituita una risposta INVALID_REQUEST.

Specifica i percorsi

Le richieste di percorsi campionati vengono indicate tramite l'utilizzo dei parametri path e samples, che indicano una richiesta di dati sull'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 sull'altitudine solo in corrispondenza dei vertici, le richieste di percorso vengono campionate lungo la lunghezza del percorso, in base al numero di samples specificati (inclusi i punti di arrivo).

Il parametro path può accettare uno dei seguenti argomenti:

  • Un array di due o più stringhe di testo di coordinate separate da virgole, separate utilizzando il carattere barra verticale ("|"): path=40.714728,-73.998672|-34.397,150.644
  • Coordinate codificate utilizzando l'algoritmo della polilinea codificata: path=enc:gfo}EtohhUxD@bAxJmGF

Le stringhe di 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 località valida sulla superficie terrestre. Le latitudini possono assumere qualsiasi valore compreso tra -90 e 90, mentre i valori di longitudine possono assumere qualsiasi valore compreso tra -180 e 180. Se specifichi un valore di latitudine o longitudine non valido, la tua richiesta verrà rifiutata come richiesta non valida.

Puoi passare fino a 512 coordinate all'interno di un array o di una polilinea codificata, creando comunque un URL valido. Tieni presente che, quando passi più coordinate, l'accuratezza dei dati restituiti potrebbe avere una risoluzione inferiore rispetto a quando richiedi i dati per una singola coordinata. Se superi i 512 punti o coordinate nei parametri "locations" o "path", viene restituita una risposta INVALID_REQUEST.

Risposte di elevazione

  • Un array di due o più stringhe di testo di coordinate separate da virgole, separate utilizzando il carattere barra verticale ("|"): path=40.714728,-73.998672|-34.397,150.644
  • Coordinate codificate utilizzando l'algoritmo della polilinea codificata: path=enc:gfo}EtohhUxD@bAxJmGF

Le stringhe di 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 località valida sulla superficie terrestre. Le latitudini possono assumere qualsiasi valore compreso tra -90 e 90, mentre i valori di longitudine possono assumere qualsiasi valore compreso tra -180 e -180. Se specifichi un valore di latitudine o longitudine non valido, la tua richiesta verrà rifiutata come richiesta non valida.

Puoi passare fino a 512 coordinate all'interno di un array o di una polilinea codificata, creando comunque un URL valido. Tieni presente che, quando passi più coordinate, l'accuratezza dei dati restituiti potrebbe avere una risoluzione inferiore rispetto a quando richiedi i dati per una singola coordinata. Se superi i 512 punti o coordinate nei parametri "locations" o "path", viene restituita una risposta INVALID_REQUEST.

Risposte di elevazione

Per ogni richiesta valida, il servizio Elevation restituisce una risposta Elevation nel formato indicato nell'URL della richiesta.

ElevationResponse

Campo Obbligatorio Tipo Descrizione
elemento obbligatorio Array<ElevationResult> Per saperne di più, consulta ElevationResult.
elemento obbligatorio ElevationStatus Per saperne di più, consulta ElevationStatus.
facoltativo stringa

Quando il servizio restituisce un codice di stato diverso da OK, potrebbe essere presente un campo error_message aggiuntivo all'interno dell'oggetto della risposta. Questo campo contiene informazioni più dettagliate sui motivi alla base del codice di stato specificato. Questo campo non viene restituito sempre e i suoi contenuti sono soggetti a modifiche.

ElevationStatus

Codici di stato restituiti dal servizio.

  • OK, che indica che la richiesta API è andata a buon fine.
  • DATA_NOT_AVAILABLE che indica che non sono disponibili dati per le località di input.
  • INVALID_REQUEST che indica che la richiesta API non è corretta.
  • OVER_DAILY_LIMIT che indicano uno dei seguenti elementi:
    • La chiave API è mancante o non valida.
    • La fatturazione non è stata abilitata sul tuo account.
    • È stato superato un limite di utilizzo autoimposto.
    • Il metodo di pagamento fornito non è più valido (ad esempio, una carta di credito è scaduta).
  • OVER_QUERY_LIMIT che indica che il richiedente ha superato la quota.
  • REQUEST_DENIED che indica che l'API non ha completato la richiesta.
  • UNKNOWN_ERROR che indica un errore sconosciuto.

Se il codice di stato è diverso da OK, potrebbe essere presente un campo error_message aggiuntivo all'interno dell'oggetto ElevationResponse. 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

Campo Obbligatorio Tipo Descrizione
elemento obbligatorio numero

L'altitudine della località in metri.
elemento obbligatorio LatLngLiteral

Un elemento di località della posizione per cui vengono calcolati i dati sull'altitudine. Tieni presente che per le richieste di percorso, l'insieme di elementi di località conterrà i punti campionati lungo il percorso.

Per saperne di più, consulta LatLngLiteral.

facoltativo numero

Il valore che indica la distanza massima tra i punti dati da cui è stata interpolata l'altitudine, in metri. Questa proprietà non sarà presente se la risoluzione non è nota. Tieni presente che i dati sull'altitudine diventano più approssimativi (valori di risoluzione più elevati) quando vengono passati più punti. Per ottenere il valore di altitudine più accurato per un punto, questo deve essere interrogato in modo indipendente.

LatLngLiteral

Un oggetto che descrive una posizione specifica con latitudine e longitudine in gradi decimali.

Campo Obbligatorio Tipo Descrizione
elemento obbligatorio numero

Latitudine in gradi decimali
elemento obbligatorio numero

Longitudine in gradi decimali

Esempi di elevazione posizionale

L'esempio seguente richiede l'altitudine di Denver, Colorado, la "Mile High City":

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 per la Death Valley, CA).

Questa richiesta mostra l'utilizzo 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 mostra l'utilizzo del 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 di seguito 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 i dati di altitudine lungo una linea retta path dal Monte Whitney, in California, a Badwater, in California, i punti più alti e più bassi degli Stati Uniti continentali. Chiediamo tre samples, quindi verranno inclusi i due endpoint e il punto intermedio.

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>