Usługa Elevation

Przegląd

Usługa Elevation dostarcza dane o wysokości dla lokalizacji na powierzchni Ziemi, w tym o głębokości na dnie oceanu (które zwracają wartości ujemne). Jeśli Google nie ma dokładnych pomiarów wysokości w dokładnej lokalizacji, o którą prosisz, usługa przeprowadzi interpolację i zwróci uśrednioną wartość na podstawie 4 najbliższych lokalizacji.

Obiekt ElevationService udostępnia prosty interfejs do wysyłania zapytań o dane dotyczące wysokości w różnych miejscach na świecie. Możesz też poprosić o próbkowane dane o wysokości wzdłuż ścieżek, co pozwoli Ci obliczyć zmiany wysokości w równych odstępach na trasach. Obiekt ElevationService komunikuje się z usługą wysokości interfejsu API Map Google, która odbiera żądania dotyczące wysokości i zwraca dane o wysokości.

Dzięki usłudze Elevation możesz tworzyć aplikacje dla pieszych i rowerzystów, aplikacje do pozycjonowania mobilnego lub aplikacje do geodezji o niskiej rozdzielczości.

Pierwsze kroki

Zanim zaczniesz korzystać z usługi Elevation w Maps JavaScript API, upewnij się, że interfejs Elevation API jest włączony w konsoli Google Cloud 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 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 na liście, nie musisz nic robić. Jeśli interfejsu API nie ma na liście, włącz go:
    1. U góry strony kliknij WŁĄCZ API, aby wyświetlić kartę Biblioteka. Możesz też wybrać Biblioteka w menu po lewej stronie.
    2. Wyszukaj Elevation API, a następnie wybierz go z listy wyników.
    3. Kliknij WŁĄCZ. Po zakończeniu procesu Elevation API pojawi się na liście interfejsów API w panelu.

Ceny i zasady

Ceny

Informacje o cenach i zasadach użytkowania usługi JavaScript Elevation znajdziesz w sekcji Korzystanie i rozliczenia dotyczącej interfejsu Elevation API.

Zasady

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

Prośby o podniesienie uprawnień

Dostęp do usługi Elevation jest asynchroniczny, ponieważ interfejs API Map Google musi wykonać wywołanie do serwera zewnętrznego. Z tego powodu 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 Elevation zwraca kod stanu (ElevationStatus) i tablicę oddzielnych obiektów ElevationResult.

ElevationService obsługuje 2 rodzaje żądań:

  • Żądania dotyczące oddzielnych, odrębnych lokalizacji za pomocą metody getElevationForLocations(), która przekazuje listę co najmniej 1 lokalizacji za pomocą obiektu LocationElevationRequest.
  • Żądania dotyczące wysokości serii połączonych punktów na ścieżce za pomocą metody getElevationAlongPath(), która przekazuje uporządkowany zbiór wierzchołków ścieżki w obiekcie PathElevationRequest. W przypadku żądania wysokości wzdłuż ścieżek musisz też przekazać parametr wskazujący, ile próbek chcesz pobrać wzdłuż tej ścieżki.

Każda z tych metod musi też przekazywać metodę wywołania zwrotnego, aby obsługiwać zwracane obiekty ElevationResult i ElevationStatus.

Prośby o podniesienie uprawnień do lokalizacji

Literał obiektu LocationElevationRequest zawiera to pole:

{
  locations[]: LatLng
}

locations (wymagany) określa lokalizacje na Ziemi, dla których mają zostać zwrócone dane dotyczące wysokości. Ten parametr przyjmuje tablicę obiektów LatLng.

Możesz przekazać dowolną liczbę współrzędnych w tablicy, o ile nie przekroczysz limitów usługi. Pamiętaj, że gdy przekazujesz wiele współrzędnych, dokładność zwracanych danych może być niższa niż w przypadku żądania danych dotyczących pojedynczych współrzędnych.

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

Literał obiektu PathElevationRequest zawiera te pola:

{
  path[]: LatLng,
  samples: Number
}

Pola te zostały opisane poniżej:

  • path (wymagany) określa ścieżkę na Ziemi, dla której mają zostać zwrócone dane dotyczące wysokości. Parametr path definiuje zbiór co najmniej 2 uporządkowanych par {szerokość,długość geograficzna} za pomocą tablicy co najmniej 2 obiektów LatLng.
  • samples (wymagany) określa liczbę punktów próbkowania na ścieżce, dla których mają zostać zwrócone dane o wysokości. Parametr samples dzieli podany element path na uporządkowany zbiór punktów równoodległych wzdłuż ścieżki.

Podobnie jak w przypadku żądań pozycyjnych parametr path określa zestaw wartości szerokości i długości geograficznej. Jednak w odróżnieniu od żądania pozycyjnego path określa uporządkowany zbiór wierzchołków. Zamiast zwracać dane o wysokości w wierzchołkach, żądania ścieżki są próbkowane na całej długości ścieżki, gdzie każda próbka jest równo oddalona od pozostałych (w tym od punktów końcowych).

Reakcje na podwyższone tętno

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

Stany uprawnień

Każda prośba o podniesienie uprawnień zwraca kod ElevationStatus w funkcji wywołania zwrotnego. Ten kod status będzie zawierać jedną z tych wartości:

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

Sprawdź, czy wywołanie zwrotne się powiodło, sprawdzając ten kod stanu dla OK.

Wyniki dotyczące wysokości

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

  • Element location (zawierający obiekty LatLng) pozycji, dla której obliczane są dane wysokości. Pamiętaj, że w przypadku żądań ścieżki zbiór 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 maksymalną odległość między punktami danych, z których interpolowano wysokość, w metrach. Jeśli rozdzielczość jest nieznana, ta właściwość nie będzie dostępna. Pamiętaj, że gdy przekazywanych jest wiele punktów, dane o wysokości stają się mniej dokładne (większe wartości resolution). Aby uzyskać jak najdokładniejszą wartość wysokości punktu, należy wysłać zapytanie niezależnie.

Przykłady wysokości

Poniższy kod przekształca kliknięcie na mapie w żądanie wysokości za pomocą obiektu LocationElevationRequest:

TypeScript

async function init(): Promise<void> {
    const [{ InfoWindow }, { ElevationService }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('elevation'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;

    const elevator = new ElevationService();
    const infowindow = new InfoWindow();

    infowindow.open(innerMap);

    // Add a listener for the click event. Display the elevation for the LatLng of
    // the click inside the infowindow.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        displayLocationElevation(event.latLng!, elevator, infowindow, innerMap);
    });
}

function displayLocationElevation(
    location: google.maps.LatLng,
    elevator: google.maps.ElevationService,
    infowindow: google.maps.InfoWindow,
    map: google.maps.Map
) {
    // Format numeric values to two decimal places
    const formatter = new Intl.NumberFormat(undefined, {
        maximumFractionDigits: 2,
    });

    // Initiate the location request
    elevator
        .getElevationForLocations({
            locations: [location],
        })
        .then(({ results }) => {
            if (results[0]) {
                const { elevation, location: resultLocation } = results[0];
                infowindow.setPosition(resultLocation);
                infowindow.setContent(
                    `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.`
                );
            } else {
                infowindow.setPosition(location);
                infowindow.setContent('No results found');
            }

            infowindow.open(map);
        })
        .catch((e: unknown) => {
            infowindow.setContent(
                `Elevation service failed due to: ${String(e)}`
            );
        });
}

void init();

JavaScript

async function init() {
    const [{ InfoWindow }, { ElevationService }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('elevation'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    const elevator = new ElevationService();
    const infowindow = new InfoWindow();

    infowindow.open(innerMap);

    // Add a listener for the click event. Display the elevation for the LatLng of
    // the click inside the infowindow.
    innerMap.addListener('click', (event) => {
        displayLocationElevation(event.latLng, elevator, infowindow, innerMap);
    });
}

function displayLocationElevation(location, elevator, infowindow, map) {
    // Format numeric values to two decimal places
    const formatter = new Intl.NumberFormat(undefined, {
        maximumFractionDigits: 2,
    });

    // Initiate the location request
    elevator
        .getElevationForLocations({
            locations: [location],
        })
        .then(({ results }) => {
            if (results[0]) {
                const { elevation, location: resultLocation } = results[0];
                infowindow.setPosition(resultLocation);
                infowindow.setContent(
                    `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.`
                );
            } else {
                infowindow.setPosition(location);
                infowindow.setContent('No results found');
            }

            infowindow.open(map);
        })
        .catch((e) => {
            infowindow.setContent(
                `Elevation service failed due to: ${String(e)}`
            );
        });
}

void init();
Zobacz przykład

W poniższym przykładzie tworzona jest linia łamana na podstawie zestawu współrzędnych i wyświetlane są dane o wysokości wzdłuż tej ścieżki za pomocą interfejsu Google Visualization API. (Musisz wczytać ten interfejs API za pomocą Google Common Loader). Żądanie wysokości nad poziomem morza jest tworzone 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 }, // 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;
Zobacz przykład