Usługa Elevation

Omówienie

Usługa Elevation udostępnia dane wysokościowe dotyczące lokalizacji na powierzchni Ziemi, w tym głębokości na dnie oceanu (które zwracają wartości ujemne). Jeśli Google nie ma dokładnych pomiarów wysokości w miejscu, którego dotyczy Twoje żądanie, usługa interpoluje i zwraca średnią wartość na podstawie 4 najbliższych lokalizacji.

Obiekt ElevationService udostępnia prosty interfejs do wysyłania zapytań o dane dotyczące rzeźby terenu w różnych miejscach na świecie. Dodatkowo możesz poprosić o próbkowane dane dotyczące wysokości na ścieżkach, co pozwoli Ci obliczyć zmiany wysokości na równych odstępach na trasach. Obiekt ElevationService komunikuje się z usługą Google Maps API Elevation Service, która odbiera żądania dotyczące wysokości i zwraca dane o wysokości.

Dzięki usłudze Elevation możesz tworzyć aplikacje do wędrówek i rowerowych, aplikacje do pozycjonowania mobilnego oraz aplikacje do pomiarów w niskiej rozdzielczości.

Pierwsze kroki

Zanim użyjesz usługi Elevation w interfejsie Maps JavaScript API, upewnij się, że interfejs Elevation API jest włączony w konsoli Google Cloud w tym samym projekcie, który został skonfigurowany dla interfejsu Maps JavaScript API.

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

  1. Otwórz konsolę Google Cloud.
  2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam projekt skonfigurowany dla interfejsu Maps JavaScript API i kliknij Otwórz.
  3. Na liście interfejsów API w panelu odszukaj Elevation API.
  4. Jeśli interfejs API jest widoczny na liście, nie musisz nic więcej robić. Jeśli interfejs API nie jest wymieniony, włącz go:
    1. U góry strony kliknij WŁĄCZ INTERFEJS API, aby wyświetlić kartę Biblioteka. Możesz też w menu po lewej stronie wybrać Biblioteka.
    2. Wyszukaj Elevation API i wybierz go na liście wyników.
    3. Wybierz WŁĄCZ. Po zakończeniu procesu interfejs Elevation API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

Ceny

Od 16 lipca 2018 r. w przypadku Map, Tras i Miejsc obowiązuje nowy abonament oparty na płatnościach „pay-as-you-go”. Aby dowiedzieć się więcej o nowych cenach i limitach korzystania z usługi Elevation w JavaScript, zapoznaj się z sekcją Korzystanie i rozliczenia w dokumentacji interfejsu Elevation API.

Zasady

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

Prośby o podniesienie poziomu

Dostęp do usługi Elevation jest asynchroniczny, ponieważ interfejs API Map Google musi wykonać wywołanie do zewnętrznego serwera. Z tego powodu musisz przekazać metodę callback, która zostanie wykonana po zakończeniu przetwarzania żądania. Ta metoda wywołania zwrotnego powinna przetwarzać wyniki. Pamiętaj, że usługa Elevation zwraca kod stanu (ElevationStatus) oraz tablicę obiektów ElevationResult.

Usługa ElevationService obsługuje 2 rodzaje żądań:

  • Prośby o oddzielne, odrębne lokalizacje za pomocą metody getElevationForLocations(), której przekazywana jest lista co najmniej 1 lokalizacji za pomocą obiektu LocationElevationRequest.
  • Żądania dotyczące wysokości na serii połączonych punktów wzdłuż ścieżki za pomocą metody getElevationAlongPath(), której przekazywany jest uporządkowany zbiór wierzchołków ścieżki w obiekcie PathElevationRequest. Gdy żądasz informacji o wysokościach wzdłuż ścieżek, musisz też przekazać parametr określający, ile próbek chcesz uzyskać na tej ścieżce.

Każda z tych metod musi też przekazywać metodę wywołania zwrotnego, która obsługuje zwracane obiekty ElevationResult i ElevationStatus.

Prośby o podniesienie poziomu lokalizacji

Obiekt dosłowny LocationElevationRequest zawiera to pole:

{
  locations[]: LatLng
}

locations (wymagany) definiuje(-ują) lokalizacje na Ziemi, z których mają zostać zwrócone dane dotyczące rzeźby terenu. Ten parametr przyjmuje tablicę wartości LatLng.

Możesz przekazać dowolną liczbę wielokrotnych współrzędnych w tablicy, o ile nie przekroczysz limitów usługi. Pamiętaj, że gdy podasz wiele współrzędnych, dokładność zwróconych danych może być mniejsza niż w przypadku żądania danych dla pojedynczej współrzędnej.

Przykładowe żądania dotyczące wysokości ścieżki

Obiekt dosłowny PathElevationRequest zawiera te pola:

{
  path[]: LatLng,
  samples: Number
}

Poniżej opisujemy te pola:

  • path (wymagany) określa ścieżkę na Ziemi, dla której mają zostać zwrócone dane o wysokości. Parametr path definiuje zbiór co najmniej 2 uporządkowanych par {latitude,longitude} za pomocą tablicy zawierającej co najmniej 2 obiekty LatLng.
  • samples (wymagane) określa liczbę punktów na ścieżce, dla których mają być zwracane dane wysokości. Parametr samples dzieli daną ścieżkę pathna uporządkowany zbiór punktów równoodległych wzdłuż ścieżki.

Podobnie jak w przypadku żądań dotyczących pozycji, parametr path określa zestaw wartości szerokości i długości geograficznej. W odróżnieniu od żądania pozycjonowania path określa jednak uporządkowany zbiór wierzchołków. Zamiast zwracać dane o wysokości w wierzchołkach, żądania dotyczące ścieżki są próbkowane wzdłuż długości ścieżki, przy czym każdy próbka jest w równej odległości od siebie (w tym punkty końcowe).

Odpowiedzi na wzrost

W przypadku każdego prawidłowego żądania usługa Elevation zwróci zdefiniowanemu wywołaniu zwrotnemu zestaw obiektów ElevationResult oraz obiekt ElevationStatus.

Stany wzniesienia

Każde żądanie podwyższania uprawnień zwraca kod ElevationStatus w swojej funkcji wywołania zwrotnego. Ten kod status będzie zawierać jedną z tych wartości:

  • OK wskazujący, że żądanie usługi zostało zrealizowane
  • INVALID_REQUEST wskazujący, że żądanie usługi było nieprawidłowe
  • OVER_QUERY_LIMIT wskazujący, że osoba przesyłająca prośbę przekroczyła limit
  • REQUEST_DENIED oznacza, że usługa nie zrealizowała żądania, prawdopodobnie z powodu nieprawidłowego parametru.
  • UNKNOWN_ERROR oznaczający nieznany błąd

Aby sprawdzić, czy wywołanie zwrotne się udało, sprawdź kod stanu OK.

Wyniki wzniesienia

W przypadku powodzenia argument results funkcji wywołania zwrotnego będzie zawierać zbiór obiektów ElevationResult. Te obiekty zawierają te elementy:

  • Element location (zawierający obiekty LatLng) pozycji, dla której obliczane są dane dotyczące wzniesienia. Pamiętaj, że w przypadku żądań ścieżki zbiór elementów location będzie zawierać wylosowane punkty na ścieżce.
  • Element elevation wskazujący wysokość lokalizacji w metrach.
  • Wartość resolution, która wskazuje maksymalną odległość między punktami danych, z których interpolowano wzniesienie, w metrach. Ta właściwość nie będzie dostępna, jeśli rozdzielczość jest nieznana. Pamiętaj, że dane dotyczące wysokości stają się bardziej ogólne (większe wartości resolution) po uwzględnieniu większej liczby punktów. Aby uzyskać najdokładniejszy odczyt wysokości dla punktu, należy go zapytać niezależnie.

Przykłady wzniesienia

Ten kod przekształca kliknięcie na mapie w żądanie dotyczące elewacji przy użyciu 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 }, // 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
Zobacz przykład

Wypróbuj próbkę

W tym przykładzie tworzymy łamany na podstawie zestawu współrzędnych i wyświetlamy dane dotyczące wysokości wzdłuż tej ścieżki za pomocą interfejsu Google Visualization API. (musisz załadować ten interfejs API za pomocą Google Common Loader). Prośba o podniesienie uprawnień jest tworzona za pomocą funkcji 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
Zobacz przykład

Wypróbuj próbkę