Panoramica
Il servizio elevazione fornisce dati altimetrici relativi alle località sulla superficie terrestre, inclusi i luoghi in profondità nel fondale oceanico (che restituiscono valori negativi). Nei casi in cui Google non disponga di misurazioni dell'altitudine esatte nella posizione esatta da te richiesta, il servizio interpolerà e restituirà un valore medio utilizzando le quattro località più vicine.
L'oggetto ElevationService
offre una semplice interfaccia per eseguire query sulla posizione della Terra per i dati sull'altitudine. Inoltre, puoi richiedere dati di altitudine campionati lungo i percorsi, in modo da calcolare i dislivelli equidistanti lungo i percorsi. L'oggetto ElevationService
comunica
con il servizio API di Google Maps Elevation Service, che riceve richieste di elevazione
e restituisce dati sull'elevazione.
Con il servizio Elevation, puoi sviluppare applicazioni per escursioni a piedi e in bicicletta, applicazioni di posizionamento mobile o applicazioni di rilevamento a bassa risoluzione.
Come iniziare
Prima di utilizzare il servizio Elevation nell'API Maps JavaScript, assicurati che l'API Elevation sia abilitata nella console Google Cloud, nello stesso progetto che hai configurato per l'API Maps JavaScript.
Per visualizzare l'elenco delle API abilitate:
- Vai alla console Google Cloud.
- Fai clic sul pulsante Seleziona un progetto, quindi seleziona lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
- Nell'elenco delle API nella Dashboard, cerca API Elevation.
- Se vedi l'API nell'elenco, significa che è tutto a posto. Se l'API non è nell'elenco, abilitala:
- Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Raccolta dal menu laterale a sinistra.
- Cerca l'API Elevation, quindi selezionala dall'elenco dei risultati.
- Seleziona ABILITA. Al termine della procedura, l'API Elevation viene visualizzata nell'elenco delle API sulla Dashboard.
Prezzi e norme
Prezzi
Il 16 luglio 2018 è entrato in vigore un nuovo piano tariffario di pagamento a consumo per Maps, Routes e Places. Per scoprire di più sui nuovi prezzi e limiti di utilizzo per l'utilizzo del servizio JavaScript Elevation, consulta Utilizzo e fatturazione per l'API Elevation.
Criteri
L'utilizzo del servizio Elevation deve essere conforme ai criteri descritti per l'API Elevation.
Richieste di altitudine
L'accesso al servizio Elevation è asincrono, poiché l'API di Google Maps deve effettuare una chiamata a un server esterno. Per questo motivo, devi passare un metodo di callback da eseguire al completamento della richiesta. Questo
metodo di callback dovrebbe elaborare i risultati. Tieni presente che il
servizio Altitudine restituisce un codice di stato
(ElevationStatus
) e un array di oggetti ElevationResult
separati.
ElevationService
gestisce due tipi di richieste:
- Richieste di località discrete separate utilizzando il metodo
getElevationForLocations()
, a cui viene trasmesso un elenco di una o più località utilizzando un oggettoLocationElevationRequest
. - Richieste di elevazione su una serie di punti connessi lungo un percorso utilizzando il metodo
getElevationAlongPath()
, che viene trasmesso un insieme ordinato di vertici del percorso all'interno di un oggettoPathElevationRequest
. Quando richiedi altitudini lungo i percorsi, devi anche trasmettere un parametro che indica quanti campioni vuoi intraprendere lungo il percorso.
Ciascuno di questi metodi deve anche passare un metodo di callback per gestire gli oggetti ElevationResult
e ElevationStatus
restituiti.
Richieste di elevazione posizione
Un valore letterale dell'oggetto LocationElevationRequest
contiene il seguente campo:
{ locations[]: LatLng }
locations
(obbligatorio) definisce le località sulla Terra da cui restituire i dati sull'altitudine. Questo parametro accetta un array di LatLng
.
All'interno di un array puoi passare un numero qualsiasi di più coordinate, a condizione di non superare le quote di servizio. Tieni presente che quando si passa più coordinate, l'accuratezza dei dati restituiti potrebbe avere una risoluzione inferiore rispetto a quella utilizzata per la richiesta dei dati per una singola coordinata.
Richieste di elevazione del percorso campionate
Un valore letterale oggetto PathElevationRequest
contiene i seguenti campi:
{ path[]: LatLng, samples: Number }
Questi campi sono spiegati di seguito:
path
(obbligatorio) definisce un percorso sul pianeta per il quale restituire i dati sull'altitudine. Il parametropath
definisce un insieme di due o più coppie ordinate di {latitudine,longitudine} utilizzando un array di due o più oggettiLatLng
.samples
(obbligatorio) specifica il numero di punti di esempio lungo un percorso per cui restituire i dati sull'altitudine. Il parametrosamples
suddivide il valorepath
specificato in un insieme ordinato di punti equidistanti lungo il percorso.
Come per le richieste di posizione, il parametro path
specifica un insieme di valori di latitudine e longitudine. Tuttavia, a differenza di una richiesta di posizionamento, path
specifica un insieme ordinato di vertici. Anziché restituire i dati sull'elevazione ai vertici, le richieste del percorso vengono campionate lungo la lunghezza del percorso, dove ogni campione è equidistante l'uno dall'altro (inclusi gli endpoint).
Risposte altitudine
Per ogni richiesta valida, il servizio Elevation restituisce
al callback definito un insieme di oggetti ElevationResult
insieme a un oggetto ElevationStatus
.
Stati altitudine
Ogni richiesta di altitudine restituisce un codice ElevationStatus
all'interno della relativa funzione di callback. Questo codice status
conterrà uno dei seguenti valori:
OK
, che indica che la richiesta di servizio è andata a buon fineINVALID_REQUEST
, a indicare che il formato della richiesta di servizio non è correttoOVER_QUERY_LIMIT
, a indicare che il richiedente ha superato la quotaREQUEST_DENIED
indica che il servizio non ha completato la richiesta, probabilmente a causa di un parametro non validoUNKNOWN_ERROR
indica un errore sconosciuto
Devi verificare che il callback sia riuscito esaminando questo
codice di stato per OK
.
Risultati altitudine
Se l'operazione ha esito positivo, l'argomento results
della funzione di callback conterrà un insieme di oggetti ElevationResult
.
Questi oggetti contengono i seguenti elementi:
- Un elemento
location
(contenente oggettiLatLng
) della posizione per cui vengono calcolati i dati sull'elevazione. Tieni presente che per le richieste percorso, l'insieme di elementilocation
conterrà i punti campionati lungo il percorso. - Un elemento
elevation
che indica l'elevazione della posizione in metri. - Un valore
resolution
che indica la distanza massima in metri tra i punti dati da cui è stata interpolata l'altitudine. Questa proprietà non sarà presente se la risoluzione non è nota. Tieni presente che i dati sull'altitudine diventano più approssimativi (valoriresolution
più grandi) quando vengono passati più punti. Per ottenere il valore di altitudine più accurato di un punto, è necessario eseguire query indipendenti.
Esempi di altitudine
Il seguente codice converte un clic su una mappa in una richiesta di altitudine utilizzando l'oggetto LocationElevationRequest
:
TypeScript
function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 8, center: { lat: 63.333, lng: -150.5 }, // Denali. mapTypeId: "terrain", } ); const elevator = new google.maps.ElevationService(); const infowindow = new google.maps.InfoWindow({}); infowindow.open(map); // Add a listener for the click event. Display the elevation for the LatLng of // the click inside the infowindow. map.addListener("click", (event) => { displayLocationElevation(event.latLng, elevator, infowindow); }); } function displayLocationElevation( location: google.maps.LatLng, elevator: google.maps.ElevationService, infowindow: google.maps.InfoWindow ) { // Initiate the location request elevator .getElevationForLocations({ locations: [location], }) .then(({ results }) => { infowindow.setPosition(location); // Retrieve the first result if (results[0]) { // Open the infowindow indicating the elevation at the clicked position. infowindow.setContent( "The elevation at this point <br>is " + results[0].elevation + " meters." ); } else { infowindow.setContent("No results found"); } }) .catch((e) => infowindow.setContent("Elevation service failed due to: " + e) ); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 8, center: { lat: 63.333, lng: -150.5 }, // Denali. mapTypeId: "terrain", }); const elevator = new google.maps.ElevationService(); const infowindow = new google.maps.InfoWindow({}); infowindow.open(map); // Add a listener for the click event. Display the elevation for the LatLng of // the click inside the infowindow. map.addListener("click", (event) => { displayLocationElevation(event.latLng, elevator, infowindow); }); } function displayLocationElevation(location, elevator, infowindow) { // Initiate the location request elevator .getElevationForLocations({ locations: [location], }) .then(({ results }) => { infowindow.setPosition(location); // Retrieve the first result if (results[0]) { // Open the infowindow indicating the elevation at the clicked position. infowindow.setContent( "The elevation at this point <br>is " + results[0].elevation + " meters.", ); } else { infowindow.setContent("No results found"); } }) .catch((e) => infowindow.setContent("Elevation service failed due to: " + e), ); } window.initMap = initMap;
Prova Samples
L'esempio seguente crea una polilinea in base a un insieme di coordinate
e mostra i dati di altitudine lungo il percorso utilizzando
l'
API di visualizzazione Google. (Devi caricare questa API utilizzando il Common Loader di Google). Viene creata una richiesta di altitudine utilizzando
PathElevationRequest
:
TypeScript
// Load the Visualization API and the columnchart package. // @ts-ignore TODO update to newest visualization library google.load("visualization", "1", { packages: ["columnchart"] }); function initMap(): void { // The following path marks a path from Mt. Whitney, the highest point in the // continental United States to Badwater, Death Valley, the lowest point. const path = [ { lat: 36.579, lng: -118.292 }, // Mt. Whitney { lat: 36.606, lng: -118.0638 }, // Lone Pine { lat: 36.433, lng: -117.951 }, // Owens Lake { lat: 36.588, lng: -116.943 }, // Beatty Junction { lat: 36.34, lng: -117.468 }, // Panama Mint Springs { lat: 36.24, lng: -116.832 }, ]; // Badwater, Death Valley const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 8, center: path[1], mapTypeId: "terrain", } ); // Create an ElevationService. const elevator = new google.maps.ElevationService(); // Draw the path, using the Visualization API and the Elevation service. displayPathElevation(path, elevator, map); } function displayPathElevation( path: google.maps.LatLngLiteral[], elevator: google.maps.ElevationService, map: google.maps.Map ) { // Display a polyline of the elevation path. new google.maps.Polyline({ path: path, strokeColor: "#0000CC", strokeOpacity: 0.4, map: map, }); // Create a PathElevationRequest object using this array. // Ask for 256 samples along that path. // Initiate the path request. elevator .getElevationAlongPath({ path: path, samples: 256, }) .then(plotElevation) .catch((e) => { const chartDiv = document.getElementById( "elevation_chart" ) as HTMLElement; // Show the error code inside the chartDiv. chartDiv.innerHTML = "Cannot show elevation: request failed because " + e; }); } // Takes an array of ElevationResult objects, draws the path on the map // and plots the elevation profile on a Visualization API ColumnChart. function plotElevation({ results }: google.maps.PathElevationResponse) { const chartDiv = document.getElementById("elevation_chart") as HTMLElement; // Create a new chart in the elevation_chart DIV. const chart = new google.visualization.ColumnChart(chartDiv); // Extract the data from which to populate the chart. // Because the samples are equidistant, the 'Sample' // column here does double duty as distance along the // X axis. const data = new google.visualization.DataTable(); data.addColumn("string", "Sample"); data.addColumn("number", "Elevation"); for (let i = 0; i < results.length; i++) { data.addRow(["", results[i].elevation]); } // Draw the chart using the data within its DIV. chart.draw(data, { height: 150, legend: "none", // @ts-ignore TODO update to newest visualization library titleY: "Elevation (m)", }); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// Load the Visualization API and the columnchart package. // @ts-ignore TODO update to newest visualization library google.load("visualization", "1", { packages: ["columnchart"] }); function initMap() { // The following path marks a path from Mt. Whitney, the highest point in the // continental United States to Badwater, Death Valley, the lowest point. const path = [ { lat: 36.579, lng: -118.292 }, // Mt. Whitney { lat: 36.606, lng: -118.0638 }, // Lone Pine { lat: 36.433, lng: -117.951 }, // Owens Lake { lat: 36.588, lng: -116.943 }, // Beatty Junction { lat: 36.34, lng: -117.468 }, // Panama Mint Springs { lat: 36.24, lng: -116.832 }, ]; // Badwater, Death Valley const map = new google.maps.Map(document.getElementById("map"), { zoom: 8, center: path[1], mapTypeId: "terrain", }); // Create an ElevationService. const elevator = new google.maps.ElevationService(); // Draw the path, using the Visualization API and the Elevation service. displayPathElevation(path, elevator, map); } function displayPathElevation(path, elevator, map) { // Display a polyline of the elevation path. new google.maps.Polyline({ path: path, strokeColor: "#0000CC", strokeOpacity: 0.4, map: map, }); // Create a PathElevationRequest object using this array. // Ask for 256 samples along that path. // Initiate the path request. elevator .getElevationAlongPath({ path: path, samples: 256, }) .then(plotElevation) .catch((e) => { const chartDiv = document.getElementById("elevation_chart"); // Show the error code inside the chartDiv. chartDiv.innerHTML = "Cannot show elevation: request failed because " + e; }); } // Takes an array of ElevationResult objects, draws the path on the map // and plots the elevation profile on a Visualization API ColumnChart. function plotElevation({ results }) { const chartDiv = document.getElementById("elevation_chart"); // Create a new chart in the elevation_chart DIV. const chart = new google.visualization.ColumnChart(chartDiv); // Extract the data from which to populate the chart. // Because the samples are equidistant, the 'Sample' // column here does double duty as distance along the // X axis. const data = new google.visualization.DataTable(); data.addColumn("string", "Sample"); data.addColumn("number", "Elevation"); for (let i = 0; i < results.length; i++) { data.addRow(["", results[i].elevation]); } // Draw the chart using the data within its DIV. chart.draw(data, { height: 150, legend: "none", // @ts-ignore TODO update to newest visualization library titleY: "Elevation (m)", }); } window.initMap = initMap;