Servizio di altezza

Panoramica

Il servizio Elevation fornisce dati altimetrici relativi alle località sulla superficie della Terra, incluse le località in profondità sul fondale oceanico (che restituiscono valori negativi). Nei casi in cui Google non disponga di misurazioni esatte dell'elevazione nella posizione esatta richiesta, il servizio interpolerà e restituirà un valore mediano utilizzando le quattro località più vicine.

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

Con il servizio Altitudine, puoi sviluppare applicazioni per escursioni e ciclismo, applicazioni di posizionamento mobile o applicazioni di rilevamento a bassa risoluzione.

Per iniziare

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

Per visualizzare l'elenco delle API abilitate:

  1. Vai alla console Google Cloud.
  2. Fai clic sul pulsante Seleziona un progetto, poi seleziona lo stesso progetto 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 è presente nell'elenco, attivala:
    1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Raccolta. In alternativa, nel menu a sinistra, seleziona Raccolta.
    2. Cerca API Elevation e selezionala dall'elenco dei risultati.
    3. Seleziona ATTIVA. Al termine del processo, Elevation API viene visualizzata nell'elenco delle API nella dashboard.

Prezzi e norme

Prezzi

A partire dal 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 sui limiti di utilizzo per l'utilizzo del servizio Elevation JavaScript, consulta Utilizzo e fatturazione per l'API Elevation.

Norme

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

Richieste di dati altimetrici

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

ElevationService gestisce due tipi di richieste:

  • Richieste di località distinte e separate utilizzando il metodo getElevationForLocations(), a cui viene passato un elenco di una o più località utilizzando un oggetto LocationElevationRequest.
  • Richieste di elevazione su una serie di punti collegati lungo un percorso utilizzando il metodo getElevationAlongPath(), a cui viene passato un insieme ordinato di vertici del percorso all'interno di un oggetto PathElevationRequest. Quando richiedi le altezze lungo i percorsi, devi anche passare un parametro che indichi quanti campioni vuoi acquisire lungo il percorso.

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

Richieste di altezza della località

Un valore letterale dell'oggetto LocationElevationRequest contiene il seguente campo:

{
  locations[]: LatLng
}

locations (obbligatorio) definisce le località sulla Terra da cui restituire i dati di altitudine. Questo parametro accetta un array di LatLng.

Puoi passare un numero qualsiasi di coordinate multiple all'interno di un array, a condizione che non superi le quote del servizio. Tieni presente che, se passi più coordinate, la precisione dei dati restituiti potrebbe essere di risoluzione inferiore rispetto a quando richiedi i dati per una singola coordinata.

Richieste di altezza del percorso campionate

Un valore letterale dell'oggetto PathElevationRequest contiene i seguenti campi:

{
  path[]: LatLng,
  samples: Number
}

Questi campi sono descritti di seguito:

  • path (obbligatorio) definisce un percorso sulla Terra per il quale restituire i dati di altitudine. Il parametro path definisce un insieme di due o più coppie {latitude,longitude} in ordine utilizzando un array di due o più oggetti LatLng.
  • samples (obbligatorio) specifica il numero di punti campionati 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.

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 pathposizione, path specifica un insieme ordinato di vertici. Anziché restituire i dati sull'elevazione ai vertici, le richieste di percorsi vengono campionate lungo la lunghezza del percorso, dove ogni campione è equidistante dall'altro (inclusi i punti finali).

Risposte all'altitudine

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

Stati di altitudine

Ogni richiesta di elevazione 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 fine
  • INVALID_REQUEST che indica che la richiesta di servizio non è stata formattata correttamente
  • OVER_QUERY_LIMIT che indica che l'autore della richiesta 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 che indica un errore sconosciuto

Devi verificare che il tuo callback sia andato a buon fine esaminando questo codice di stato per OK.

Risultati relativi all'elevazione

In caso di 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 oggetti LatLng) della posizione per cui vengono calcolati i dati sull'elevazione. Tieni presente che per le richieste di percorso, l'insieme di elementi location conterrà i punti campionati lungo il percorso.
  • Un elemento elevation che indica l'elevazione della località in metri.
  • Un valore resolution che indica la distanza massima in metri tra i punti dati da cui è stata interpolata l'elevazione. Questa proprietà non sarà presente se la risoluzione non è nota. Tieni presente che i dati sull'elevazione diventano più approssimativi (valori resolution più elevati) quando vengono passati più punti. Per ottenere il valore di elevazione più accurato per un punto, è necessario eseguire una query in modo indipendente.

Esempi di altezza

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;
index.ts

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;
index.js
Visualizza esempio

Prova Sample

L'esempio seguente crea un polilinea a partire da un insieme di coordinate e mostra i dati sull'elevazione lungo il percorso utilizzando l' API Google Visualization. Devi caricare questa API utilizzando il caricatore Google Common. Una richiesta di elevazione viene creata 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;
index.ts

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;
index.js
Visualizza esempio

Prova Sample