Usługa wzniesienia

Przegląd

Usługa wysokości względnej udostępnia dane o wysokości dotyczące lokalizacji na powierzchni ziemi, w tym głębokość lokalizacji na dnie oceanu (które zwracają wartości ujemne). W przypadkach, gdy Google nie ma dokładnych pomiarów wysokości w dokładnie wybranej lokalizacji, usługa interpoluje i zwraca średnią wartość za pomocą czterech najbliższych lokalizacji.

Obiekt ElevationService udostępnia prosty interfejs do wysyłania zapytań o lokalizacje na Ziemi w celu uzyskania danych o wzniesieniu. Możesz też poprosić o próbkowanie danych dotyczących wysokości wzdłuż ścieżek, aby obliczyć odpowiednie zmiany wysokości na trasach. Obiekt ElevationService komunikuje się z usługą Elevation API w Mapach Google, która odbiera żądania o wzniesieniu i zwraca dane o wysokości.

Usługa elewacji umożliwia tworzenie aplikacji dla wycieczek pieszych i rowerowych, aplikacji do pozycjonowania mobilnego oraz aplikacji do geodezji.

Pierwsze kroki

Zanim użyjesz usługi Elevation API w Maps JavaScript API, najpierw upewnij się, że interfejs Elevation API jest włączony w Google Cloud Console w tym samym projekcie, który masz skonfigurowany w Maps JavaScript API.

Aby wyświetlić listę włączonych interfejsów API:

  1. Otwórz Google Cloud Console.
  2. Kliknij przycisk Wybierz projekt, a następnie wybierz ten sam projekt, który został skonfigurowany dla interfejsu Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Elevation API.
  4. Jeśli interfejs API jest widoczny na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. U góry strony wybierz WŁĄCZ API, aby wyświetlić kartę Biblioteka. W menu po lewej stronie możesz też wybrać Biblioteka.
    2. Wyszukaj interfejs Elevation API i wybierz go z listy wyników.
    3. Kliknij WŁĄCZ. Gdy proces dobiegnie końca, interfejs Elevation API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

Ceny

16 lipca 2018 roku w Mapach, trasach i miejscach jest dostępny nowy cennik płatności według wykorzystania. Więcej informacji o nowych limitach cen i wykorzystania podczas korzystania z usługi Elevation API znajdziesz w artykule Usage and Billing (Użycie i płatności) do wykorzystania w interfejsie Elevation API.

Zasady

Korzystanie z usługi Elevation musi być zgodne z zasadami opisanymi w interfejsie Elevation API.

Prośby o wzniesienie

Dostęp do usługi Elevation jest asynchroniczny, bo API Map Google musi wywoływać serwer zewnętrzny. Z tego powodu musisz przekazać metodę wywołania zwrotnego, aby wykonać żądanie. Ta metoda wywołania zwrotnego powinna przetworzyć wyniki. Zwróć uwagę, że usługa Elevator zwraca kod stanu (ElevationStatus) oraz tablicę oddzielnych obiektów ElevationResult.

ElevationService obsługuje 2 typy żądań:

  • Żądania osobnych lokalizacji konkretnych przy użyciu metody getElevationForLocations(), która jest przekazywana do listy co najmniej 1 lokalizacji za pomocą obiektu LocationElevationRequest.
  • Żądania dotyczące wysokości w szeregu połączonych punktów na ścieżce przy użyciu metody getElevationAlongPath(), która jest przekazywana do zestawu wierzchołków ścieżki w obiekcie PathElevationRequest. Wysyłając prośbę o wzniesienie wzdłuż ścieżek, musisz też przekazać parametr wskazujący liczbę prób, które chcesz obrać w tej ścieżce.

Każda z tych metod musi też przekazywać metodę wywołania zwrotnego, by obsługiwała zwrócone obiekty ElevationResult i ElevationStatus.

Prośby o podniesienie lokalizacji

Literał obiektu LocationElevationRequest zawiera to pole:

{
  locations[]: LatLng
}

Atrybut locations (wymagany) określa lokalizacje na Ziemi, z których mają być zwracane dane o wysokości. Ten parametr przyjmuje tablicę LatLng s.

W tablicy możesz ustawić dowolną liczbę wielu współrzędnych, pod warunkiem że nie przekroczysz limitów usługi. Pamiętaj, że w przypadku przesyłania wielu współrzędnych dokładność zwracanych danych może być niższa niż w przypadku żądania pojedynczej współrzędnej.

Próbki wzniesienia ścieżki

Literał obiektu PathElevationRequest zawiera te pola:

{
  path[]: LatLng,
  samples: Number
}

Te pola objaśniamy poniżej.

  • Atrybut path (wymagany) definiuje ścieżkę na Ziemi, dla której należy zwracać dane o wysokości. Parametr path określa zestaw 2 lub większej liczby par {szerokość_długości geograficznej}, używając tablicy zawierającej co najmniej 2 obiekty LatLng.
  • samples (wymagany) określa liczbę przykładowych punktów na ścieżce, do których mają być zwracane dane wysokości. Parametr samples dzieli podany argument path na uporządkowany zestaw równoważnych punktów na ścieżce.

Tak jak w przypadku żądań pozycjonowania, parametr path określa zestaw szerokości i długości geograficznej. W przeciwieństwie do żądania pozycjonującego path określa jednak uporządkowany zestaw wierzchołków. Zamiast zwracać dane o wysokości na wierzchołkach, żądania próbek ścieżek są próbkowane wzdłuż długości ścieżki, gdzie każda próbka jest oddalona od siebie (włącznie z punktami końcowymi).

Reakcje na wysokość

W przypadku każdego prawidłowego żądania usługa Elevator powróci do zdefiniowanego wywołania zwrotnego obiektu ElevationResult i obiektu ElevationStatus.

Stany wysokości

Każde żądanie wysokości zwraca kod ElevationStatus w funkcji wywołania zwrotnego. Kod status zawiera jedną z tych wartości:

  • OK wskazuje, że żądanie usługi zostało zrealizowane
  • Wartość INVALID_REQUEST wskazująca, że żądanie usługi było uszkodzone
  • OVER_QUERY_LIMIT wskazuje, że żądający przekroczył limit
  • REQUEST_DENIED wskazuje, że usługa nie zakończyła żądania, prawdopodobnie z powodu nieprawidłowego parametru
  • UNKNOWN_ERROR oznacza nieznany błąd

Aby sprawdzić, czy wywołanie zwrotne zostało zrealizowane, przeanalizuj ten kod stanu w: OK.

Wyniki wzniesienia

Po sukcesie argument results Twojej funkcji wywołania zwrotnego będzie zawierać zbiór obiektów ElevationResult. Obiekty te zawierają następujące elementy:

  • Element location (zawierający obiekty LatLng) pozycji, dla której obliczane są dane o wysokości. Pamiętaj, że w przypadku żądań ścieżki zestaw elementów location będzie zawierał punkty na ścieżce.
  • Element elevation wskazujący wysokość w metrach.
  • Wartość resolution wskazująca maksymalną odległość w metrach między punktami danych, w których nastąpiła interpolacja wysokości. Jeśli ta rozdzielczość nie jest znana, nie będzie tej właściwości. Pamiętaj, że dane o wzniesieniu stają się bardziej przybliżone (większe wartości resolution), gdy przekazywanych jest wiele punktów. Aby uzyskać najdokładniejszą wartość wysokości punktu, należy je wysyłać niezależnie.

Przykłady wysokości

Ten kod przekształca kliknięcie mapy w żądanie wysokości, używając obiektu 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 },
    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
Zobacz przykład

Fragment

Poniższy przykład pokazuje tworzenie łamanej na podstawie zestawu współrzędnych i wyświetlanie danych wysokości na tej ścieżce za pomocą interfejsu GoogleWizualizacj API. Ten interfejs API musisz wczytać za pomocą Google Load Loader. Prośba o wzniesienie jest tworzona za pomocą 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 },
    { 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
Zobacz przykład

Fragment