Richieste di altitudine e risposte

Richieste di altezza

Le richieste all'API Elevation vengono create come stringa URL. L'API restituisce i dati di altitudine per le località sulla Terra. Puoi specificare i dati sulla posizione in uno dei due modi seguenti:

• Come insieme di uno o più locations.
• Come una serie di punti collegati lungo una path.

Entrambi gli approcci utilizzano le coordinate di latitudine/longitudine per identificare le località o i vertici del percorso. Questo documento descrive il formato obbligatorio degli URL dell'API Elevation e i parametri disponibili.

L'API Elevation restituisce i dati per query su un singolo punto della massima precisione possibile. Le query in batch che coinvolgono più località potrebbero restituire dati con minore precisione, soprattutto se le località sono diverse, poiché i dati vengono semplificati.

Una richiesta dell'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 <ElevationResponse> nodo.

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 durante la creazione degli URL. Tieni presente che anche browser, proxy e server possono avere limiti di caratteri URL differenti.

HTTPS è richiesto 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 per località discrete o per un percorso ordinato. Per le località distinte, le richieste di altezza restituiscono i dati sulle località specifiche passate nella richiesta; per i percorsi, le richieste di altezza vengono invece campionate lungo il percorso specificato.

Come standard in tutti gli URL, i parametri vengono separati dal carattere e commerciale (&). L'elenco dei parametri e i relativi possibili valori sono indicati di seguito.

Tutte le richieste

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

Richieste di posizione

• locations (obbligatorio) definisce le località sulla Terra da cui restituire i dati di 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 è previsto un limite di 512 punti. Per ulteriori informazioni, consulta la sezione Specifica delle località di seguito.

Richieste di percorsi campionati

• path (obbligatorio) definisce un percorso sulla Terra per il quale restituire i dati sull'elevazione. Questo parametro definisce un insieme di due o più coppie {latitude,longitude} ordinate che definiscono un percorso lungo la superficie della Terra. Questo parametro deve essere utilizzato in combinazione con il parametro samples descritto di seguito. Il limite per questo parametro specifico è di 512 punti. Per ulteriori informazioni, consulta la sezione Specifica dei percorsi di seguito.
• samples (obbligatorio) specifica il numero di punti di campione lungo un percorso per i quali restituire i dati sull'elevazione. Il parametro samples divide il path specificato in un insieme ordinato di punti equidistanti lungo il percorso.

Specifica delle località

Le richieste di posizione vengono indicate tramite l'uso del parametro locations, che indica le richieste di altezza per le posizioni specifiche passate come valori di latitudine/longitudine.

Il parametro locations può assumere i seguenti argomenti:

• Una sola 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 polilinea codificato: locations=enc:gfo}EtohhU

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" è un valore locations valido. I valori di latitudine e longitudine devono corrispondere a una posizione valida sulla faccia della Terra. 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 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 essere di risoluzione inferiore rispetto alla richiesta di 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 percorsi campionati vengono indicate tramite l'uso dei parametri path e samples, che indicano una richiesta di dati di elevazione 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'elevazione solo ai vertici, le richieste di percorso vengono campionate lungo la lunghezza del percorso, in base al numero di samples specificati (inclusi i punti finali).

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 Algoritmo polilinea codificato: 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 posizione valida sulla faccia della Terra. 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 trasmetti più coordinate, la precisione dei dati restituiti potrebbe essere inferiore a quella richiesta per 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 relative all'altitudine

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

Se il codice di stato è diverso da OK, potrebbe esserci un campo error_message aggiuntivo nell'oggetto Risposta elevazione. 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:

L'oggetto location include i seguenti elementi:

Esempi di elevazione posizionale

L'esempio seguente richiede l'elevazione per Denver, Colorado, "Mile High City" nel formato JSON:

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>

L'esempio seguente mostra più risposte (per Denver, Colorado e per Death Valley, California).

Questa richiesta dimostra l'utilizzo del flag JSON output:

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'

Questa richiesta dimostra 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.

{
  "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>

I seguenti esempi richiedono i dati di altitudine lungo una linea retta path dal Monte Whitney, CA a Badwater, CA, dai punti più alti e più bassi degli Stati Uniti continentali. Chiediamo tre samples, che includeranno i due endpoint e il punto a metà.

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>