„Elevation“-Dienst

Übersicht

Über den Elevation-Dienst erhalten Sie Höhendaten für Standorte auf der Erde und auch für tiefer liegende Orte unter dem Meeresspiegel, die dann als negative Werte zurückgegeben werden. Falls Google keine genauen Höhenmessungen für den von Ihnen angeforderten Standort vorliegen, führt der Dienst eine Interpolation aus und gibt einen Durchschnittswert auf Basis der 4 am nächsten gelegenen Standorte zurück.

Das ElevationService-Objekt bietet eine einfache Oberfläche, über die Höhendaten für Standorte auf der Erde abgefragt werden können. Außerdem können Sie Höhendaten anfragen, die in gleichmäßigen Abständen entlang von Pfaden gesammelt werden und so die Höhenunterschiede für verschiedene Abschnitte oder die gesamte Route berechnen. Das ElevationService-Objekt kommuniziert mit dem Elevation-Dienst der Google Maps API, bei dem Höhenanfragen eingehen und über den Höhendaten ausgegeben werden.

Mithilfe des Elevation-Dienstes können Sie Anwendungen zum Wandern und Radfahren, Positionsanwendungen oder Überwachungsanwendungen mit niedriger Auflösung entwickeln.

Erste Schritte

Bevor Sie den Elevation-Dienst in der Maps JavaScript API verwenden können, müssen Sie die Elevation API in der Google Cloud Console in dem Projekt aktivieren, das Sie für die Maps JavaScript API eingerichtet haben.

So öffnen Sie die Liste der aktivierten APIs:

  1. Rufen Sie die Google Cloud Console auf.
  2. Klicken Sie auf die Schaltfläche Projekt auswählen, wählen Sie das Projekt aus, das Sie für die Maps JavaScript API eingerichtet haben, und klicken Sie dann auf Öffnen.
  3. Suchen Sie im Dashboard in der Liste der APIs nach Elevation API.
  4. Wenn die API in der Liste angezeigt wird, müssen Sie nichts weiter tun. Ist die API nicht aufgeführt, aktivieren Sie sie:
    1. Wählen Sie oben auf der Seite API AKTIVIEREN aus, um den Tab Bibliothek aufzurufen. Sie haben auch die Möglichkeit, im Menü auf der linken Seite Bibliothek auszuwählen.
    2. Suchen Sie nach der Elevation API und wählen Sie sie dann in der Ergebnisliste aus.
    3. Klicken Sie auf AKTIVIEREN. Die Elevation API wird dann in der Liste der APIs auf dem Dashboard angezeigt.

Preise und Richtlinien

Preise

Seit 16. Juli 2018 gilt für Maps, Routes und Places ein neues nutzungsorientiertes Preismodell (Pay as you go). Weitere Informationen zu den aktuellen Preisen und Nutzungslimits für die Verwendung des JavaScript-Elevation-Dienstes finden Sie unter Nutzung und Abrechnung für die Elevation API.

Richtlinien

Die Nutzung des Elevation-Dienstes muss den Richtlinien für die Elevation API entsprechen.

Höhendaten anfragen

Der Zugriff auf den Elevation-Dienst erfolgt asynchron, da dazu der Aufruf eines externen Servers über die Google Maps API erforderlich ist. Daher muss eine Callback-Methode übergeben werden, die nach Abschluss der Anfrage ausgeführt wird. Das Ergebnis wird dann über die Callback-Methode verarbeitet. Der Höhendienst gibt einen Statuscode (ElevationStatus) und ein Array mit separaten ElevationResult-Objekten zurück.

Der ElevationService verarbeitet zwei Typen von Anfragen:

  • Anfragen für einzelne, eigenständige Standorte über die getElevationForLocations()-Methode, wobei eine Liste mit mindestens einem Standort über ein LocationElevationRequest-Objekt weitergegeben wird
  • Anfragen für einen aus einer Reihe verbundener Punkte bestehenden Pfad über die getElevationAlongPath()-Methode, wobei ein geordneter Satz von Pfadeckpunkten innerhalb eines PathElevationRequest-Objektes weitergegeben wird. Bei Höhenanfragen für Pfade müssen Sie außerdem einen Parameter übergeben, mit dem festgelegt wird, wie viele Höhenangaben entlang des Pfades ermittelt werden sollen.

Bei jeder dieser Methoden muss außerdem eine Callback-Methode übergeben werden, mit der die zurückgegebenen ElevationResult- und ElevationStatus-Objekte verarbeitet werden.

Höhendaten für Standorte anfragen

Ein LocationElevationRequest-Objektliteral enthält das folgende Feld:

{
  locations[]: LatLng
}

locations (erforderlich): definiert die Standorte auf der Erde, für die Höhendaten zurückgegeben werden sollen. Dieser Parameter wird mit einem Array von LatLng-Werten gefüllt.

Sie können in einem Array eine beliebige Anzahl mehrerer Koordinaten übergeben, solange die Kontingente für den Dienst nicht überschritten werden. Wenn mehrere Koordinaten weitergegeben werden, sind die zurückgegebenen Daten möglicherweise ungenauer, als wenn Sie Daten für Einzelkoordinaten anfordern.

Höhendaten entlang von Pfaden anfordern

Ein PathElevationRequest-Objektliteral enthält folgende Felder:

{
  path[]: LatLng,
  samples: Number
}

Diese Felder werden im Folgenden beschrieben:

  • path (erforderlich): definiert einen Pfad auf der Erde, für den Höhendaten zurückgegeben werden sollen. Der path-Parameter definiert mithilfe eines Arrays von mindestens 2 LatLng-Objekten einen Satz von 2 oder mehr geordneten Paaren aus Breiten- und Längengrad.
  • samples (erforderlich): gibt die Anzahl der Beispielpunkte entlang eines Pfades an, für die Höhendaten zurückgegeben werden sollen. Der samples-Parameter unterteilt den angegebenen path in einen geordneten Satz von Punkten, die sich in gleichen Abständen entlang des Pfades befinden.

Wie bei Positionsanfragen wird mit dem path-Parameter ein Satz von Breiten- und Längengradwerten angegeben. Anders als bei Positionsanfragen wird mit dem path-Parameter jedoch ein geordneter Satz von Eckpunkten angegeben. Es werden aber keine Höhendaten für die Eckpunkte geliefert, sondern die Daten werden an Punkten erhoben, die in gleichmäßigen Abständen auf den gesamten Pfad verteilt sind, einschließlich der Endpunkte.

Antworten für Höhendatenanfragen

Für jede gültige Anfrage gibt der Elevation-Dienst an die festgelegte Callback-Funktion eine Reihe von ElevationResult-Objekten sowie ein ElevationStatus-Objekt zurück.

Höhenstatus

Bei jeder Höhenanfrage wird ein ElevationStatus-Code innerhalb der zugehörigen Callback-Funktion zurückgegeben. Dieser status-Code enthält einen der folgenden Werte:

  • OK: Die Dienstanfrage war erfolgreich.
  • INVALID_REQUEST: Die Dienstanfrage war falsch formatiert.
  • OVER_QUERY_LIMIT: Der Anforderer hat das Kontingent überschritten.
  • REQUEST_DENIED: Der Dienst hat die Anfrage nicht vollständig ausgeführt, wahrscheinlich aufgrund eines ungültigen Parameters.
  • UNKNOWN_ERROR: Ein unbekannter Fehler ist aufgetreten.

Sie sollten überprüfen, ob die Callback-Funktion wie gewünscht funktioniert. Sehen Sie dazu nach, ob der Statuscode OK ist.

Höhenergebnisse

Bei Erfolg enthält das results-Argument Ihrer Callback-Funktion eine Reihe von ElevationResult-Objekten. In diesen Objekten sind die folgenden Elemente enthalten:

  • Ein location-Element mit LatLng-Objekten für die Position, für die Höhendaten berechnet werden sollen. Bei Pfadanfragen enthält der Satz von location-Elementen die Punkte für die Höhenermittlung entlang des Pfades.
  • Ein elevation-Element, das die Höhe des Standorts in Metern angibt
  • Ein resolution-Wert, der in Metern die maximale Entfernung zwischen Datenpunkten anzeigt, von denen aus die Höhe interpoliert wurde. Falls die Auflösung nicht bekannt ist, fehlt dieses Attribut. Beachten Sie, dass Höhendaten ungenauer werden und somit größere resolution-Werte haben, wenn mehrere Punkte übergeben werden. Um einen möglichst genauen Höhenwert für einen Punkt zu erhalten, sollte er einzeln abgefragt werden.

Höhenbeispiele

Mit dem folgenden Code wird ein Klick auf einer Karte mithilfe des LocationElevationRequest-Objektes in eine Höhenanfrage umgewandelt:

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 },
    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
Beispiel ansehen

Testbeispiel

Im folgenden Beispiel wird eine Polylinie anhand einer Reihe von Koordinaten erstellt. Entlang des Pfades werden über die Google Visualization API Höhendaten angezeigt. Sie müssen die API mithilfe von Google Common Loader laden. Höhenanfragen werden mit PathElevationRequest erstellt:

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 },
    { 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;
index.js
Beispiel ansehen

Testbeispiel