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 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 precisione possibile. Le query batch che coinvolgono più località possono restituire dati con meno precisione, soprattutto se le località sono distanti, poiché si verifica un certo livellamento dei dati.

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

Nota: per essere validi, gli URL devono essere codificati correttamente e sono limitati a 16384 caratteri per tutti i servizi web. Tieni presente questo limite durante la creazione degli URL. Tieni presente che browser diversi, anche i proxy e i server potrebbero avere limiti di caratteri 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 sia per località discrete o per un percorso ordinato. Per le località discrete, le richieste di ritorno dell'altitudine Dati sulle località specifiche trasmesse nella richiesta; per i percorsi, le richieste di elevazione vengono invece campionate lungo il percorso specificato.

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

Tutte le richieste

• key - (obbligatorio) La tua domanda di adesione chiave API. Questa chiave identifica l'applicazione ai fini della gestione della quota. Scopri come ottenere una chiave.

Richieste di posizionamento

• locations (obbligatorio) definisce le località sulla Terra da cui restituire i dati sull'elevazione. Questo parametro utilizza un parametro singola località come coppia di {latitude,longitude} separata da virgole (ad es. "40.714728,-73.998672") o più coppie latitudine/longitudine passati come una matrice o come una 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 insieme al parametro samples descritto di seguito. Il limite è di 512 punti. parametro specifico. Per ulteriori informazioni, consulta la sezione Specifica dei percorsi di seguito.
• samples (obbligatorio) specifica il numero di campioni i punti lungo un percorso per il quale restituire dati di elevazione. La Il parametro samples divide il valore path specificato in un insieme ordinato di punti equidistanti lungo il percorso.

Specifica delle località

Le richieste di posizionamento sono indicate attraverso l'utilizzo Parametro locations, che indica le richieste di elevazione per le località specifiche trasmesse valori di latitudine/longitudine.

Il parametro locations può assumere le seguenti opzioni argomenti:

• Una sola coordinata: locations=40.714728,-73.998672
• Un array di coordinate separate dalla barra verticale ("|") carattere: locations=40.714728,-73.998672|-34.397,150.644
• Un insieme di coordinate codificate utilizzando Codificato Algoritmo polilinea: 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 superficie terrestre. Le latitudini possono assumere qualsiasi valore compreso tra -90 e 90, mentre i valori della longitudine possono assumere qualsiasi valore compreso tra -180 e 180. Se specifichi un valore per la latitudine o la longitudine non valido, la richiesta verrà rifiutata come richiesta non valida.

Puoi passare fino a 512 coordinate all'interno di una matrice o codificate polilinea, creando comunque un URL valido. Tieni presente che, se passi più coordinate, l'accuratezza dei dati restituiti potrebbe essere inferiore rispetto alla richiesta di dati per una singola coordinata. Se superi 512 punti o coordinate nei parametri "locations" o "path", viene restituita una risposta INVALID_REQUEST.

Specifica dei percorsi

Le richieste di percorsi campionati vengono indicate tramite l'uso dell'elemento path e samples, che indicano una richiesta di dati di altitudine lungo un percorso a intervalli specifici. Come per le richieste posizionali, utilizzando locations, il parametro path specifica un insieme di valori di latitudine e longitudine. A differenza di una richiesta di posizionamento, 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 di termine).

Il parametro path può utilizzare una delle seguenti opzioni 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
• Codifica le coordinate utilizzando Codificato Algoritmo polilinea: path=enc:gfo}EtohhUxD@bAxJmGF

Le stringhe di coordinate di latitudine e longitudine vengono definite tramite numerali all'interno di una stringa di testo separata da virgole. Ad esempio: "40.714728,-73.998672|-34.397, 150.644" è un valido Valore path. 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 per la latitudine o la longitudine non valido, la richiesta verrà rifiutata come richiesta non valida.

Puoi passare fino a 512 coordinate all'interno di un array o di un polilinea codificato, pur continuando a creare un URL valido. Tieni presente che quando trasmetti più coordinate, la precisione dei dati restituiti può essere di risoluzione inferiore rispetto a quando si richiedono 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à un valore Elevation nel formato indicato nell'URL della richiesta.

Quando il codice di stato è diverso da OK, all'interno dell'oggetto di risposta Elevazione potrebbe essere presente un altro campo error_message. Questo campo contiene altri dati informazioni 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 di Denver, Colorado, la "città a un'altitudine di 1000 metri", in 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 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.

{
  "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 elevazione lungo una linea retta path dal Mt. Whitney, California a Badwater, CA, la regione più alta e i punti più bassi negli Stati Uniti continentali. Chiediamo tre samples, in modo da includere i due endpoint e il punto intermedio.

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>