Richieste di altitudine e risposte

Richieste di altitudine

Le richieste API Elevation vengono create come stringa URL. L'API restituisce i dati di altitudine per luoghi sulla Terra. Tu specifichi i dati sulla posizione in uno dei due seguenti modi:

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

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

L'API Elevation restituisce i dati per le query su un singolo punto con la massima precisione possibile. Query in batch che coinvolgono più località potrebbe restituire dati con una precisione minore, soprattutto se le località sono distribuite a parte, man mano che 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); o
• xml, indica l'output in XML, aggregato all'interno di una <ElevationResponse> nodo.

Nota: gli URL devono essere codificato correttamente siano validi e non superino i 16.384 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 è 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à 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 di parametri e i relativi valori possibili sono indicati di seguito.

Tutte le richieste

• key - (obbligatorio) La tua applicazione 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à nella terra da cui restituire i dati di 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. Il limite è di 512 punti. per questo parametro specifico. Per ulteriori informazioni, consulta la sezione Specifica delle località di seguito.

Richieste di percorso campionate

• path (obbligatorio) definisce un percorso sulla Terra per che restituisce i dati di altitudine. Questo parametro definisce un insieme di due più coppie ordinate di {latitude,longitude} 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.

Specificare le 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 vengono definite tramite numerali in una stringa di testo separata da virgole. Ad esempio "40.714728,-73.998672" è un valore locations valido. Latitudine e i valori di 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 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, quando passi più coordinate, la precisione dei dati restituiti potrebbe avere una risoluzione inferiore rispetto a quando si richiedono dati per una singola coordinata. Superamento di 512 punti o coordinate nelle "località" o "percorso" restituisce un 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. Invece di restituire elevazione dei dati solo ai vertici, le richieste di percorso vengono campionate lungo lunghezza del percorso, in base al numero di samples specificato (inclusi gli endpoint).

Il parametro path può utilizzare una delle seguenti opzioni argomenti:

• Un array di due o più stringhe di testo con coordinate separate da virgole separati dalla barra verticale ("|") carattere: 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 in 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 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 quando trasmetti più coordinate, la precisione dei dati restituiti può essere di risoluzione inferiore rispetto a quando si richiedono dati per una singola coordinata. Superamento di 512 punti o coordinate nelle "località" o "percorso" restituisce una risposta INVALID_REQUEST.

Risposte elevazione

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

ElevationResponse

Field	Required	Type	Description
results	required	Array<ElevationResult>	See ElevationResult for more information.
status	required	ElevationStatus	See ElevationStatus for more information.
error_message	optional	string	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, potrebbe esserci un ulteriore error_message all'interno dell'oggetto Risposta elevazione. Questo campo contiene altri dati informazioni dettagliate sui motivi alla base del codice di stato specificato.

Nota: non è garantito che questo campo sia sempre presente e i suoi possono cambiare.

La risposta contiene un array results con i seguenti elementi:

ElevationResult

Field	Required	Type	Description
elevation	required	number	The elevation of the location in meters.
location	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.
resolution	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 include i seguenti elementi:

LatLngLiteral

An object describing a specific location with Latitude and Longitude in decimal degrees.

Field	Required	Type	Description
lat	required	number	Latitude in decimal degrees
lng	required	number	Longitude in decimal degrees

Esempi di elevazione posizionale

L'esempio seguente richiede l'altitudine per Denver, Colorado, la "Mile High City" nel 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 per Death Valley, California).

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

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 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, quindi saranno inclusi i due endpoint e a metà strada.

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>