Elevation-Dienst

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Übersicht

Der Höhendienst liefert Höhendaten für Standorte auf der Erdoberfläche, einschließlich Tiefenpositionen auf dem Meeresboden, die negative Werte zurückgeben. Falls Google keine genauen Höhenmessungen für den von Ihnen angeforderten genauen Standort hat, interpoliert der Dienst und gibt einen Durchschnittswert zurück, der sich aus den vier nächstgelegenen Standorten ergibt.

Das ElevationService-Objekt bietet eine einfache Schnittstelle, mit der Höhendaten für Standorte auf der Erde abgefragt werden können. Außerdem können Sie Höhendaten stichprobenartig entlang von Pfaden abrufen und so die Höhenunterschiede entlang von Routen berechnen. Das Objekt ElevationService kommuniziert mit dem Höhendienst der Google Maps API, der Höhenanfragen empfängt und Höhendaten zurückgibt.

Mit dem Höhendienst können Sie Wander- und Fahrradanwendungen, mobile Positionierungsanwendungen oder Vermessungsanwendungen mit geringer Auflösung entwickeln.

Erste Schritte

Bevor Sie den Elevation-Dienst in der Maps JavaScript API verwenden, muss die Elevation API in der Google Cloud Console in dem Projekt aktiviert sein, das Sie für die Maps JavaScript API eingerichtet haben.

So zeigen Sie die Liste der aktivierten APIs an:

  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 in der Liste der APIs auf dem Dashboard nach Elevation API.
  4. Wenn die API in der Liste angezeigt wird, sind Sie startbereit. Wenn die API nicht aufgeführt ist, aktivieren Sie sie:
    1. Wähle oben auf der Seite API AKTIVIEREN aus, um den Tab Bibliothek aufzurufen. Alternativ kannst du im Menü auf der linken Seite Mediathek auswählen.
    2. Suchen Sie nach der Elevation API und wählen Sie sie in der Ergebnisliste aus.
    3. Wähle AKTIVIEREN aus. Wenn der Vorgang abgeschlossen ist, wird die Elevation API in der Liste der APIs im Dashboard angezeigt.

Preise und Richtlinien

Preise

Am 16. Juli 2018 traten für Maps, Routes und Places ein neues „Pay as you go“-Preismodell auf. Weitere Informationen zu den neuen Preisen und Nutzungslimits für die Verwendung des JavaScript Elevation-Diensts finden Sie unter Nutzung und Abrechnung für die Elevation API.

Ratenlimits

Beachten Sie die folgenden Hinweise zu Ratenbegrenzungen für zusätzliche Anfragen:

Das Ratenlimit wird pro Nutzersitzung angewendet, unabhängig davon, wie viele Nutzer dasselbe Projekt verwenden. Beim ersten Laden der API wird Ihnen ein anfängliches Kontingent von Anfragen zugewiesen. Wenn Sie dieses Kontingent verwenden, erzwingt die API Ratenbegrenzungen für zusätzliche Anfragen pro Sekunde. Wenn innerhalb eines bestimmten Zeitraums zu viele Anfragen gestellt werden, gibt die API einen OVER_QUERY_LIMIT-Antwortcode zurück.

Das Ratenlimit pro Sitzung verhindert die Verwendung von clientseitigen Diensten für Batchanfragen. Wenn Sie stattdessen statische, bekannte Höhen berechnen möchten, verwenden Sie den Elevation API-Webdienst.

Richtlinien

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

Höhenanforderungen

Der Zugriff auf den Höhendienst ist asynchron, da die Google Maps API einen externen Server aufrufen muss. Aus diesem Grund müssen Sie eine Callback-Methode übergeben, die bei Abschluss der Anfrage ausgeführt wird. Diese Callback-Methode sollte die Ergebnisse verarbeiten. Der Höhendienst gibt einen Statuscode (ElevationStatus) und ein Array mit separaten ElevationResult-Objekten zurück.

ElevationService verarbeitet zwei Arten von Anfragen:

  • Anfragen für separate, separate Standorte mithilfe der Methode getElevationForLocations(), der eine Liste mit einem oder mehreren Standorten mit einem LocationElevationRequest-Objekt übergeben wird.
  • Anfragen für einen aus einer Folge von verbundenen Punkten bestehenden Pfad mithilfe der Methode getElevationAlongPath(), der ein geordneter Satz von Pfadeckpunkten innerhalb eines PathElevationRequest-Objekts übergeben wird. Beim Anfordern von Höhen entlang von Pfaden müssen Sie auch einen Parameter übergeben, der angibt, wie viele Beispieldaten Sie entlang dieses Pfads abrufen möchten.

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

Standorthöhenanforderungen

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. Für diesen Parameter ist ein Array mit LatLng-Werten erforderlich.

Sie können beliebig viele Koordinaten innerhalb eines Arrays übergeben, sofern Sie die Dienstkontingente nicht überschreiten. Beachten Sie, dass beim Übergeben mehrerer Koordinaten die Genauigkeit der zurückgegebenen Daten geringer sein kann als beim Anfordern von Daten für eine einzelne Koordinate.

Pfadhöhenanforderungen mit Intervallen

Ein PathElevationRequest-Objektliteral enthält die folgenden 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 Parameter path definiert eine Gruppe von zwei oder mehr geordneten {Breitengrad,Längengrad}-Paaren mit einem Array von zwei oder mehr LatLng-Objekten.
  • samples (erforderlich) gibt die Anzahl der Beispielpunkte entlang eines Pfads an, für die Höhendaten zurückgegeben werden sollen. Der Parameter samples teilt die angegebenen path in einen geordneten Satz von abstandsgetreuen Punkten entlang des Pfads auf.

Wie bei Positionsanfragen gibt der Parameter path eine Reihe von Werten für den Breiten- und Längengrad an. Anders als bei Positionsanfragen gibt path jedoch einen geordneten Satz von Eckpunkten an. Anstatt Höhendaten an den Eckpunkten zurückzugeben, werden Pfadanfragen während des gesamten Pfads stichprobenartig erfasst, wobei jede Stichprobe gleich groß ist (einschließlich der Endpunkte).

Höhenantworten

Für jede gültige Anfrage gibt der Höhendienst an das festgelegte Callback 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 fehlerhaft.
  • OVER_QUERY_LIMIT gibt an, dass der Anfragende das Kontingent überschritten hat
  • REQUEST_DENIED: Der Dienst hat die Anfrage nicht vollständig ausgeführt, wahrscheinlich aufgrund eines ungültigen Parameters.
  • UNKNOWN_ERROR: unbekannter Fehler

Prüfen Sie anhand des Statuscodes für OK, ob der Callback erfolgreich war.

Höhenergebnisse

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

  • Ein location-Element (mit LatLng-Objekten) der Position, für die Höhendaten berechnet werden. Bei Pfadanfragen enthält der Satz von location-Elementen die Beispielpunkte entlang des Pfads.
  • Ein elevation-Element, das die Höhe des Standorts in Metern angibt.
  • Ein resolution-Wert, der die maximale Entfernung zwischen Datenpunkten angibt, von denen aus die Höhe interpoliert wurde, in Metern. Diese Property fehlt, wenn die Lösung nicht bekannt ist. Beachten Sie, dass Höhendaten ungenauer werden (größere resolution-Werte), wenn mehrere Punkte übergeben werden. Um einen möglichst genauen Höhenwert für einen Punkt zu erhalten, muss er unabhängig abgefragt werden.

Höhenbeispiele

Mit dem folgenden Code werden Klicks auf einer Karte mithilfe des Objekts LocationElevationRequest in eine Höhenanfrage übersetzt:

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;
Beispiel ansehen

Beispiel ausprobieren

Im folgenden Beispiel wird eine Polylinie anhand eines Satzes von Koordinaten konstruiert und Höhendaten entlang dieses Pfades mithilfe der Google Visualizer API angezeigt. Sie müssen diese API mit dem Google Common loader laden. Eine Höhenanfrage wird 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;

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;
Beispiel ansehen

Beispiel ausprobieren