Servizio di altitudine

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Panoramica

Il servizio Elevation fornisce dati sull'altitudine per le località sulla superficie terrestre, incluse le posizioni di profondità sul fondale oceanico (che restituiscono valori negativi). Nei casi in cui Google non possiede misurazioni precise dell'altitudine nella posizione esatta richiesta, il servizio interpolerà e restituirà un valore medio utilizzando le quattro località più vicine.

L'oggetto ElevationService fornisce un'interfaccia semplice per eseguire query sui dati relativi all'elevazione delle località sulla Terra. Inoltre, puoi richiedere dati relativi all'altitudine campionati lungo i percorsi, in modo da poter calcolare le variazioni dell'altitudine equidistanti lungo i percorsi. L'oggetto ElevationService comunica con il servizio di elevazione delle API di Google Maps, che riceve le richieste di altitudine e restituisce i dati di elevazione.

Con il servizio Elevation puoi sviluppare applicazioni per escursioni a piedi o in bicicletta, applicazioni di posizionamento mobile o applicazioni di sondaggio a bassa risoluzione.

Per cominciare

Prima di utilizzare il servizio Elevation nell'API Maps JavaScript, assicurati che l'API Elevation sia attivata in Google Cloud Console, nello stesso progetto configurato per l'API Maps JavaScript.

Per visualizzare l'elenco delle API abilitate:

  1. Vai a Google Cloud Console.
  2. Fai clic sul pulsante Seleziona un progetto, quindi scegli lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
  3. Nell'elenco delle API nella Dashboard, cerca API Elevation.
  4. Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Raccolta dal menu laterale a sinistra.
    2. Cerca l'API Elevation, quindi selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine della procedura, viene visualizzata l'API Elevation nell'elenco delle API sulla Dashboard.

Prezzi e norme

Prezzi

Dal 16 luglio 2018 è entrato in vigore un nuovo piano con pagamento a consumo per Maps, Routes e Places. Per ulteriori informazioni sui nuovi prezzi e limiti di utilizzo per il servizio JavaScript Elevation, consulta la sezione Utilizzo e fatturazione per l'API Elevation.

Norme

L'utilizzo del servizio Elevation deve essere conforme alle norme descritte per l'API Elevation.

Richieste di elevazione

L'accesso al servizio Elevation è asincrono, poiché l'API Google Maps deve effettuare una chiamata a un server esterno. Per questo motivo, devi superare un metodo di callback da eseguire al completamento della richiesta. Questo metodo di callback dovrebbe elaborare i risultati. Tieni presente che il servizio Elevazione restituisce un codice di stato (ElevationStatus) e un array di oggetti ElevationResult separati.

ElevationService gestisce due tipi di richieste:

  • Richieste di località separate e distinte utilizzando il metodo getElevationForLocations(), che trasmette un elenco di una o più località utilizzando un oggetto LocationElevationRequest.
  • Richieste di elevazione su una serie di punti connessi lungo un percorso utilizzando il metodo getElevationAlongPath(), a cui viene trasmesso un insieme ordinato di vertici di percorso all'interno di un oggetto PathElevationRequest. Quando richiedi altitudini lungo i percorsi, devi anche trasmettere un parametro che indichi quanti campioni vuoi prendere lungo quel percorso.

Ciascuno di questi metodi deve anche passare un metodo callback per gestire gli oggetti ElevationResult e ElevationStatus restituiti.

Richieste di elevazione della località

Un valore letterale di oggetto LocationElevationRequest contiene il seguente campo:

{
  locations[]: LatLng
}

locations (obbligatorio) definisce le località della Terra da cui restituire i dati relativi all'altitudine. Questo parametro utilizza un array di LatLng.

Puoi trasferire un numero qualsiasi di più coordinate all'interno di un array, a condizione che non superi le quote di servizio. Tieni presente che quando passi più coordinate, l'accuratezza di tutti i dati restituiti potrebbe essere di risoluzione inferiore rispetto a quella richiesta per i dati per una singola coordinata.

Richieste altitudine di percorsi campionate

Un valore letterale di oggetto PathElevationRequest contiene i seguenti campi:

{
  path[]: LatLng,
  samples: Number
}

Questi campi sono illustrati di seguito:

  • path (obbligatorio) definisce un percorso sulla Terra per il quale restituire dati sull'altitudine. Il parametro path definisce un insieme di due o più coppie { latitudine,longitudine} ordinate utilizzando un array di due o più oggetti LatLng.
  • samples (obbligatorio) specifica il numero di punti di esempio lungo un percorso per il quale restituire dati sull'altitudine. Il parametro samples divide il valore path specificato in un insieme ordinato di punti equidistanti lungo il percorso.

Come per le richieste posizionali, il parametro path specifica un insieme di valori di latitudine e longitudine. A differenza di una richiesta di posizione, path specifica un insieme ordinato di vertici. Anziché restituire dati di elevazione ai vertici, le richieste di percorso vengono campionate lunghe la lunghezza del percorso, dove ogni campione è equidistante tra loro (inclusi gli endpoint).

Risposte altitudine

Per ogni richiesta valida, il servizio Elevation restituirà al callback definito un insieme di oggetti ElevationResult e un oggetto ElevationStatus.

Stati di altitudine

Ogni richiesta di altitudine restituisce un codice ElevationStatus all'interno della sua funzione di callback. Questo codice status conterrà uno dei seguenti valori:

  • OK indica che la richiesta di servizio è stata eseguita correttamente
  • INVALID_REQUEST che indica che la richiesta di servizio non era valida
  • OVER_QUERY_LIMIT che indica che il richiedente ha superato la quota
  • REQUEST_DENIED che indica che il servizio non ha completato la richiesta, probabilmente a causa di un parametro non valido
  • UNKNOWN_ERROR indica un errore sconosciuto

Dovresti verificare che la richiamata sia riuscita 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 LatLng) di oggetti della posizione per cui vengono calcolati i dati di altitudine. Nota che per le richieste del percorso, l'insieme di elementi location conterrà i punti campionati lungo il percorso.
  • Elemento elevation che indica l'altitudine della località in metri.
  • Un valore resolution, che indica la distanza massima tra i punti dati da cui è stata interpolata l'altitudine, in metri. Questa proprietà verrà mancante se la risoluzione non è nota. Tieni presente che i dati sull'altitudine diventano più approssimativi (valori resolution più grandi) quando vengono trasmessi più punti. Per ottenere il valore di altitudine più accurato per un punto, devi eseguire query in modo indipendente.

Esempi di altitudine

Il seguente codice traduce un clic su una mappa in una richiesta di elevazione 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 },
    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;
Visualizza l'esempio

Prova Esempio

L'esempio seguente costruisce una polilinea in base a un insieme di coordinate e mostra i dati di altitudine lungo il percorso tramite l'API Google Visualizzazione. (Devi caricare l'API utilizzando Google Common load.) 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 },
    { lat: 36.606, lng: -118.0638 },
    { lat: 36.433, lng: -117.951 },
    { lat: 36.588, lng: -116.943 },
    { lat: 36.34, lng: -117.468 },
    { 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;
Visualizza l'esempio

Prova Esempio