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 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 dati per query su singoli punti 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); oppure
  • 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 quando crei gli URL. Tieni presente che browser, proxy e server diversi potrebbero 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 in base al fatto che la richiesta riguardi posizioni distinte o 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 sono separati utilizzando il carattere e commerciale (&amp;). 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 sull'elevazione. Questo parametro accetta una singola posizione 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 Specificare le 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. Esiste un limite di 512 punti per questo parametro specifico. Per ulteriori informazioni, consulta la sezione Specificare i 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 valore 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ò accettare i seguenti argumenti:

  • 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 per polilinee codificate: 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 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 un polilinea codificato, pur continuando a creare un URL valido. Tieni presente che, se passi più coordinate, la precisione 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'utilizzo dei parametri path e samples, che indicano una richiesta di dati sull'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 di termine).

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 di polilinee codificate: 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 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 un polilinea codificato, pur continuando a creare 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. 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.

ElevationResponse

FieldRequiredTypeDescription
required Array<ElevationResult> See ElevationResult for more information.
requiredElevationStatus See ElevationStatus for more information.
optionalstring

When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

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, all'interno dell'oggetto di risposta Elevazione potrebbe essere presente un altro campo error_message. 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

FieldRequiredTypeDescription
requirednumber

The elevation of the location in meters.

requiredLatLngLiteral

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.

optionalnumber

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.

FieldRequiredTypeDescription
requirednumber

Latitude in decimal degrees

requirednumber

Longitude in decimal degrees

Esempi di elevazione posizionale

L'esempio seguente richiede l'elevazione di Denver, Colorado, la "città a un'altitudine di 1000 metri", 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, Colorado e per Death Valley, California).

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 dati sull'elevazione lungo una linea rettapath dal Monte Whitney in California a Badwater in California, i punti più alto e più basso degli Stati Uniti continentali. Chiediamo tre samples, in modo da includere 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>