Usługa wzniesienia

Opis

Usługa Wzniesienie dostarcza dane o wysokości dla 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 żądanej lokalizacji, usługa interpoluje i zwraca uśrednioną wartość w 4 najbliższych lokalizacjach.

Obiekt ElevationService udostępnia prosty interfejs do wysyłania zapytań o dane o wysokości do lokalizacji na Ziemi. Możesz też poprosić o próbkowane dane o wysokości wzdłuż ścieżek, co pozwoli Ci obliczyć równoodległe zmiany wysokości na poszczególnych trasach. Obiekt ElevationService komunikuje się z usługą Google Maps API Elevation Service, która odbiera żądania podniesienia i zwraca dane o wysokości.

Za pomocą usługi Elevation możesz tworzyć aplikacje do wędrówek i jazdy na rowerze, aplikacje do pozycjonowania urządzeń mobilnych oraz aplikacje geodezyjne o niskiej rozdzielczości.

Pierwsze kroki

Zanim użyjesz usługi Elevation w interfejsie Maps JavaScript API, sprawdź, czy interfejs Elevation API jest włączony w Google Cloud Console w tym samym projekcie, który został skonfigurowany na potrzeby Maps JavaScript API.

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

  1. Otwórz konsolę Google Cloud.
  2. Kliknij przycisk Wybierz projekt, a następnie wybierz projekt skonfigurowany na potrzeby interfejsu Maps JavaScript API i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Elevation API.
  4. Jeśli widzisz interfejs API na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. Aby wyświetlić kartę Biblioteka, u góry strony wybierz WŁĄCZ API. Możesz też wybrać Biblioteka w menu po lewej stronie.
    2. Wyszukaj interfejs Elevation API, a następnie wybierz go na liście wyników.
    3. Wybierz WŁĄCZ. Gdy proces się zakończy, na liście interfejsów API w panelu pojawi się interfejs Elevation API.

Ceny i zasady

Ceny

16 lipca 2018 roku zaczęliśmy obowiązywać nowy abonament rozliczany według wykorzystania. W przypadku Map, tras i Miejsc Google obowiązuje nowy abonament. Aby dowiedzieć się więcej o nowych cenach i limitach wykorzystania usługi JavaScript Elevation, przeczytaj artykuł Korzystanie i płatności dotyczący interfejsu Elevation API.

Zasady

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

Prośby o podniesienie

Dostęp do usługi Elevation jest asynchroniczny, ponieważ interfejs API Map Google musi wywoływać serwer zewnętrzny. Dlatego musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu żądania. Ta metoda wywołania zwrotnego powinna przetworzyć wyniki. Zwróć uwagę, że usługa wysokości względnej zwraca kod stanu (ElevationStatus) i tablicę osobnych obiektów ElevationResult.

ElevationService obsługuje 2 typy żądań:

  • Żądania dotyczące oddzielnych, dyskretnych lokalizacji są określane przy użyciu metody getElevationForLocations(), która jest przekazywana za pomocą obiektu LocationElevationRequest z listą co najmniej 1 lokalizacji.
  • Żądania wzniesienia w serii połączonych punktów na ścieżce za pomocą metody getElevationAlongPath(), która jest przekazywana uporządkowanym zestawem wierzchołków ścieżki w obiekcie PathElevationRequest. Przy wysyłaniu prośby o wzniesienia wzdłuż ścieżek musisz też przekazać parametr wskazujący liczbę próbek, które chcesz pobrać wzdłuż tej ścieżki.

Każda z tych metod musi też przekazywać metodę wywołania zwrotnego do obsługi zwróconych obiektów ElevationResult i ElevationStatus.

Prośby o podniesienie lokalizacji

Literał obiektu LocationElevationRequest zawiera to pole:

{
  locations[]: LatLng
}

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

W tablicy możesz przekazać dowolną liczbę wielu współrzędnych, o ile nie przekroczysz limitów usługi. Pamiętaj, że podczas przekazywania wielu współrzędnych dokładność zwracanych danych może być mniejsza niż w przypadku żądań danych dla jednej współrzędnej.

Próbkowane żądania o podwyższenie ścieżki

Literał obiektu PathElevationRequest zawiera te pola:

{
  path[]: LatLng,
  samples: Number
}

Poniżej objaśniamy te pola:

  • Element path (wymagany) określa ścieżkę na Ziemi, dla której są zwracane dane o wysokości. Parametr path określa zbiór co najmniej 2 uporządkowanych par {szerokość,długość geograficzna} z tablicą składającą się z co najmniej 2 obiektów LatLng.
  • samples (wymagany) określa liczbę przykładowych punktów na ścieżce, dla których mają zostać zwrócone dane o wysokości. Parametr samples dzieli podane path na uporządkowany zestaw równoodległych punktów na ścieżce.

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

Odpowiedzi dotyczące wysokości

Dla każdego prawidłowego żądania usługa Elevation zwróci do zdefiniowanego wywołania zwrotnego zbiór obiektów ElevationResult wraz z obiektem ElevationStatus.

Stany wzniesień

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

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

Przeanalizuj ten kod stanu dla OK, aby upewnić się, że wywołanie zwrotne się powiodło.

Wyniki dotyczące wysokości

Po udanym zakończeniu argument results funkcji wywołania zwrotnego będzie zawierał zbiór obiektów ElevationResult. Te obiekty zawierają te elementy:

  • Element location (zawierający LatLng obiekty) pozycji, dla której obliczane są dane o wysokości. Pamiętaj, że w przypadku żądań ścieżki zbiór elementów location będzie zawierał próbkowane punkty wzdłuż ścieżki.
  • Element elevation wskazujący wysokość lokalizacji w metrach.
  • Wartość resolution, wskazująca w metrach maksymalną odległość między punktami danych, z których została interpolowana wysokość. Jeśli rozwiązanie nie jest znane, ta właściwość będzie niedostępna. Pamiętaj, że dane o wysokości stają się bardziej przybliżone (większe wartości resolution) po przekazaniu wielu punktów. Aby uzyskać najdokładniejszą wartość wysokości punktu, należy wykonać niezależne zapytanie.

Przykłady wzniesień

Ten kod przekształca kliknięcie na mapie na żądanie podniesienia, 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;

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;
Zobacz przykład

Wypróbuj fragment

Poniższy przykład umożliwia utworzenie linii łamanej z zestawem współrzędnych i wyświetlenie danych o wysokości wzdłuż tej ścieżki za pomocą interfejsu GoogleVisual API. Ten interfejs API musisz wczytać za pomocą programu Google Common Loader. Prośba o podniesienie uprawnień 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;

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;
Zobacz przykład

Wypróbuj fragment