Usługa wzniesienia

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Omówienie

Usługa wzniesienia udostępnia dane o wysokości dotyczące lokalizacji na powierzchni Ziemi, w tym lokalizacji głębi na dnie oceanu (które zwracają wartości ujemne). W takich przypadkach, gdy Google nie dysponuje dokładnymi pomiarami wysokości w konkretnej lokalizacji, usługa dokonuje interpolacji i zwraca średnią wartość z 4 najbliższych lokalizacji.

Obiekt ElevationService udostępnia prosty interfejs do wysyłania zapytań o lokalizacje ziemi na potrzeby danych o wysokości. Możesz również poprosić o próbkę danych wzniesień wzdłuż ścieżek, aby umożliwić obliczenie równomiernych zmian wysokości na trasach. Obiekt ElevationService komunikuje się z usługą wzniesień interfejsu API Map Google, która odbiera żądania dotyczące wysokości i zwraca dane wysokości.

Za pomocą usługi wzniesienia możesz tworzyć aplikacje na wędrówki piesze i rowerowe, aplikacje do pozycjonowania na urządzeniach mobilnych lub aplikacje do prowadzenia ankiet o niskiej rozdzielczości.

Pierwsze kroki

Zanim użyjesz usługi Elevation w interfejsie Maps JavaScript API, najpierw włącz Google Cloud Console w Google Cloud Console w tym samym projekcie, który został skonfigurowany w przypadku Maps Maps API.

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

  1. Otwórz Google Cloud Console.
  2. Kliknij przycisk Wybierz projekt, a potem wybierz ten sam projekt, który masz skonfigurowany w interfejsie Maps JavaScript API, i kliknij Otwórz.
  3. Na liście interfejsów API w panelu znajdź Elevation API.
  4. Jeśli na liście widzisz interfejs API, nie musisz nic więcej robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. U góry strony wybierz ENABLE API (Włącz interfejs API), aby wyświetlić kartę Biblioteka. Możesz też wybrać Biblioteka z menu po lewej stronie.
    2. Wyszukaj Elevation API i wybierz go z listy wyników.
    3. Wybierz WŁĄCZ. Gdy proces się zakończy, interfejs Elevation API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

cenę,

Od 16 lipca 2018 roku w Mapach, Trasach i Miejscach zaczyna obowiązywać nowy abonament. Aby dowiedzieć się więcej o nowych limitach cenowych i limitach użytkowania w związku z usługą JavaScript Elevation, zapoznaj się z sekcją Użycie i płatności dotyczącą interfejsu Elevation API.

Zasady

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

Prośby o zmianę wysokości

Dostęp do usługi wysokości jest asynchroniczny, ponieważ interfejs API Map Google musi wywoływać serwer zewnętrzny. Z tego powodu trzeba przekazać metodę wywołania zwrotnego, aby wykonać żądanie. Ta metoda wywołania zwrotnego powinna przetworzyć wyniki. Usługa wzniesienia zwraca kod stanu (ElevationStatus) i tablicę oddzielnych obiektów ElevationResult.

ElevationService obsługuje 2 typy żądań:

  • Żądania dotyczące oddzielnych, odrębnych lokalizacji przy użyciu metody getElevationForLocations(), która jest przekazywana do listy co najmniej jednej lokalizacji za pomocą obiektu LocationElevationRequest.
  • Prośby o podniesienie wysokości szeregu połączonych punktów na ścieżce przy użyciu metody getElevationAlongPath(), która jest przekazywana w uporządkowanym zestawie wierzchołków ścieżki w obiekcie PathElevationRequest. Przesyłając prośbę o wzniesienie na ścieżkach, musisz też przesłać parametr określający, ile próbek chcesz nabyć pokonać daną ścieżkę.

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

Prośby o zwiększenie 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 przyjmuje tablicę LatLng s.

W tablicy można przekazać dowolną liczbę wielu współrzędnych, o ile nie przekroczysz limitów usług. Pamiętaj, że gdy przesyłasz wiele współrzędnych, dokładność zwracanych danych może być niższa niż w przypadku żądania danych dla pojedynczej współrzędnych.

Próbki wzniesienia ścieżki przykładowej

Litera obiektu PathElevationRequest zawiera te pola:

{
  path[]: LatLng,
  samples: Number
}

Wyjaśniamy te pola:

  • path (wymagany) definiuje ścieżkę na Ziemi, dla której mają być zwracane dane o wysokości. Parametr path określa zestaw co najmniej 2 uporządkowanych par {width,length} za pomocą tablicy co najmniej 2 obiektów LatLng.
  • samples (wymagany) określa liczbę przykładowych punktów na ścieżce, w przypadku których mają być zwracane dane o wysokości. Parametr samples dzieli określony ciąg path na uporządkowany zbiór punktów równorzędnych na ścieżce.

Tak jak w przypadku żądań pozycji, parametr path określa zestaw szerokości i długości geograficznej. W przeciwieństwie do żądania pozycyjnego path określa jednak określony zestaw wierzchołków. Zamiast zwracać dane o wysokości wierzchołków, żądania dotyczące ścieżki są próbkowane w długości ścieżki, gdzie każda próbka jest odsunięta od siebie (włącznie z punktami końcowymi).

Odpowiedzi na wzniesienie

W przypadku każdego prawidłowego żądania usługa Elevation powróci do zdefiniowanego wywołania zwrotnego zestawu obiektów ElevationResult wraz z obiektem ElevationStatus.

Stany wysokości

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

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

Aby sprawdzić, czy wywołanie zwrotne jest udane, przeanalizuj ten kod stanu dla: OK.

Wyniki wzniesienia

Po sukcesie argument results funkcji wywołania zwrotnego będzie zawierać zestaw obiektów ElevationResult. Te obiekty zawierają następujące elementy:

  • Element location (zawierający obiekty LatLng) pozycji, na podstawie której obliczane są dane o wysokości. Pamiętaj, że w przypadku żądań ścieżki zestaw elementów location będzie zawierał próbkowane punkty na ścieżce.
  • Element elevation wskazujący wysokość lokalizacji w metrach.
  • Wartość resolution, która wskazuje maksymalny dystans między punktami danych, z których następuje interpolacja wysokości. Jeśli nie uda się znaleźć rozdzielczości, ta właściwość będzie niedostępna. Pamiętaj, że dane o wzniesieniu są bardziej szczegółowe (większe wartości resolution), gdy minie wiele punktów. Aby uzyskać dokładną wartość wysokości punktu, należy wykonać zapytanie niezależnie.

Przykłady wysokości

Ten kod przekłada kliknięcie mapy na żądanie dotyczące wysokości za pomocą 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

Fragment

Poniższy przykład pokazuje utworzenie linii łamanej dla zbioru współrzędnych i wyświetlanie danych wysokości na tej ścieżce przy użyciu interfejsu GoogleWizualizacj API. (Ten interfejs API musi być ładowany przez Google Common Loader). Prośba o wysokość 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

Fragment