Servizio di altezza

Panoramica

Il servizio Elevation fornisce dati altimetrici per le località sulla superficie della Terra, inclusi i punti in profondità dei fondali oceanici (che restituiscono valori negativi). Nei casi in cui Google non dispone di misurazioni altimetriche esatte nella posizione precisa richiesta, il servizio interpolerà e restituirà un valore medio utilizzando le quattro località più vicine.

L'oggetto ElevationService fornisce un'interfaccia semplice per ottenere i dati sull'elevazione di luoghi della Terra. Inoltre, puoi richiedere dati altimetrici campionati lungo i percorsi, il che ti consente di calcolare le variazioni di elevazione equidistanti lungo i percorsi. L'oggetto ElevationService comunica con il servizio Elevation dell'API di Google Maps, che riceve le richieste di elevazione e restituisce i dati altimetrici.

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.

Per 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 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, quindi seleziona 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, è tutto pronto.
      Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la Libreria scheda. In alternativa, dal menu laterale, seleziona Libreria.
    2. Cerca API Elevation, quindi selezionala dall' elenco dei risultati.
    3. Seleziona ABILITA. Al termine della procedura, API Elevation viene visualizzata nell'elenco delle API nella dashboard.

Prezzi e norme

Prezzi

Per scoprire di più sui prezzi e sulle norme di utilizzo del servizio Elevation JavaScript, consulta Utilizzo e fatturazione dell'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 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 deve elaborare i risultati. Tieni presente che il servizio Elevation restituisce un codice di stato (ElevationStatus) e un array di oggetti ElevationResult separati.

L'oggetto ElevationService gestisce due tipi di richieste:

  • Richieste per località separate e discrete utilizzando il getElevationForLocations() metodo, a cui viene passata una lista di una o più località utilizzando un LocationElevationRequest oggetto.
  • Richieste di elevazione su una serie di punti connessi lungo un percorso utilizzando il metodo getElevationAlongPath(), a cui viene passato un insieme ordinato di vertici del percorso all'interno di un PathElevationRequest oggetto. Quando richiedi le elevazioni lungo i percorsi, devi anche passare un parametro che indica quanti campioni vuoi prelevare 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 della località

Un oggetto letterale LocationElevationRequest contiene il seguente campo:

{
  locations[]: LatLng
}

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

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

Richieste di elevazione del percorso campionato

Un oggetto letterale PathElevationRequest contiene i seguenti campi:

{
  path[]: LatLng,
  samples: Number
}

Questi campi sono spiegati di seguito:

  • path (obbligatorio) definisce un percorso sulla Terra per il quale restituire i dati altimetrici. Il parametro path definisce un insieme di due o più coppie ordinate {latitudine,longitudine} di punti utilizzando un array di due o più oggetti LatLng.
  • samples (obbligatorio) specifica il numero di punti di campionamento lungo un percorso per il quale restituire i dati altimetrici. Il samples parametro divide il 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 posizionale, tuttavia, path specifica un insieme ordinato di vertici. Anziché restituire i dati altimetrici ai vertici, le richieste di percorso vengono campionate lungo la lunghezza del percorso, dove ogni campione è equidistante l'uno dall'altro (inclusi gli endpoint).

Risposte di elevazione

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

Stati di elevazione

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

  • OK indica che la richiesta di servizio è andata a buon fine
  • INVALID_REQUEST indica che la richiesta di servizio non è in un formato valido
  • OVER_QUERY_LIMIT indica che il richiedente ha superato la quota
  • REQUEST_DENIED indica che il servizio non ha completato la richiesta, probabilmente a causa di un parametro non valido
  • UNKNOWN_ERROR indica un errore sconosciuto

Devi verificare che la callback sia andata a buon fine esaminando questo codice di stato per OK.

Risultati di 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 LatLng oggetti) della posizione per cui vengono calcolati i dati altimetrici. Tieni presente che per le richieste di percorso, l'insieme di location elementi 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 tra i punti dati da cui è stata interpolata l'elevazione, in metri. Questa proprietà non sarà presente se la risoluzione non è nota. Tieni presente che i dati altimetrici diventano più grossolani (valori resolution più grandi) quando vengono passati più punti. Per ottenere il valore di elevazione più preciso per un punto, è necessario eseguire una query in modo indipendente.

Esempi di elevazione

Il seguente codice traduce un clic su una mappa in una richiesta di elevazione utilizzando l'oggetto LocationElevationRequest:

TypeScript

async function init(): Promise<void> {
    const [{ InfoWindow }, { ElevationService }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('elevation'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;

    const elevator = new ElevationService();
    const infowindow = new InfoWindow();

    infowindow.open(innerMap);

    // Add a listener for the click event. Display the elevation for the LatLng of
    // the click inside the infowindow.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        displayLocationElevation(event.latLng!, elevator, infowindow, innerMap);
    });
}

function displayLocationElevation(
    location: google.maps.LatLng,
    elevator: google.maps.ElevationService,
    infowindow: google.maps.InfoWindow,
    map: google.maps.Map
) {
    // Format numeric values to two decimal places
    const formatter = new Intl.NumberFormat(undefined, {
        maximumFractionDigits: 2,
    });

    // Initiate the location request
    elevator
        .getElevationForLocations({
            locations: [location],
        })
        .then(({ results }) => {
            if (results[0]) {
                const { elevation, location: resultLocation } = results[0];
                infowindow.setPosition(resultLocation);
                infowindow.setContent(
                    `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.`
                );
            } else {
                infowindow.setPosition(location);
                infowindow.setContent('No results found');
            }

            infowindow.open(map);
        })
        .catch((e: unknown) => {
            infowindow.setContent(
                `Elevation service failed due to: ${String(e)}`
            );
        });
}

void init();

JavaScript

async function init() {
    const [{ InfoWindow }, { ElevationService }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('elevation'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    const elevator = new ElevationService();
    const infowindow = new InfoWindow();

    infowindow.open(innerMap);

    // Add a listener for the click event. Display the elevation for the LatLng of
    // the click inside the infowindow.
    innerMap.addListener('click', (event) => {
        displayLocationElevation(event.latLng, elevator, infowindow, innerMap);
    });
}

function displayLocationElevation(location, elevator, infowindow, map) {
    // Format numeric values to two decimal places
    const formatter = new Intl.NumberFormat(undefined, {
        maximumFractionDigits: 2,
    });

    // Initiate the location request
    elevator
        .getElevationForLocations({
            locations: [location],
        })
        .then(({ results }) => {
            if (results[0]) {
                const { elevation, location: resultLocation } = results[0];
                infowindow.setPosition(resultLocation);
                infowindow.setContent(
                    `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.`
                );
            } else {
                infowindow.setPosition(location);
                infowindow.setContent('No results found');
            }

            infowindow.open(map);
        })
        .catch((e) => {
            infowindow.setContent(
                `Elevation service failed due to: ${String(e)}`
            );
        });
}

void init();
Visualizza esempio

L'esempio seguente costruisce una polilinea dato un insieme di coordinate e visualizza i dati altimetrici lungo il percorso utilizzando l' API di visualizzazione Google. (Devi caricare questa API utilizzando Google Common Loader.) Una richiesta di elevazione viene costruita 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;
Visualizza esempio