Usługa Elevation

Przegląd

Usługa Elevation udostępnia dane o wysokości dla lokalizacji na powierzchni Ziemi, w tym dane o głębokości na dnie oceanu (które zwracają wartości ujemne). W przypadkach, gdy Google nie ma dokładnych pomiarów wysokości w lokalizacji, o którą prosisz, usługa interpoluje i zwraca wartość uśrednioną 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 wzdłuż tras. Obiekt ElevationService komunikuje się z usługą wysokościową interfejsu API Map Google, która otrzymuje żądania wysokości i zwraca dane o wysokości.

Usługa Elevation umożliwia tworzenie aplikacji do pieszych i rowerowych wycieczek, aplikacji do pozycjonowania mobilnego oraz aplikacji do pomiarów o niskiej rozdzielczości.

Pierwsze kroki

Zanim zaczniesz korzystać z usługi określania wysokości 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 następnie wybierz ten sam projekt, który został 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. 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, a następnie wybierz go z listy wyników.
    3. Kliknij WŁĄCZ. Po zakończeniu procesu na panelu na liście interfejsów API pojawi się Elevation API.

Ceny i zasady

Ceny

Więcej informacji o cenach i zasadach korzystania z usługi określania wysokości w JavaScript 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.

Żądania dotyczące wysokości

Dostęp do usługi Elevation jest asynchroniczny, ponieważ interfejs API Map Google musi wywołać zewnętrzny serwer. Dlatego musisz przekazać metodę wywołania zwrotnego, która zostanie wykonana po zakończeniu żądania. Ta metoda wywołania zwrotnego powinna przetwarzać wyniki. Pamiętaj, że usługa Elevation zwraca kod stanu (ElevationStatus) i tablicę oddzielnych obiektów ElevationResult.

ElevationService obsługuje 2 typy żądań:

  • Żądania dotyczące oddzielnych, dyskretnych lokalizacji za pomocą metody getElevationForLocations(), która przekazuje listę co najmniej 1 lokalizacji za pomocą obiektu LocationElevationRequest.
  • Żądania wysokości dla serii połączonych punktów wzdłuż ścieżki za pomocą metody getElevationAlongPath(), do której przekazywany jest uporządkowany zbiór wierzchołków ścieżki w obiekcie PathElevationRequest. Podczas wysyłania żądania wysokości 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ć wywołanie zwrotne, które będzie obsługiwać zwrócone obiekty ElevationResult i ElevationStatus.

Prośby o wysokość nad poziomem morza

Literał obiektu LocationElevationRequest zawiera to pole:

{
  locations[]: LatLng
}

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

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

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

Literał obiektu PathElevationRequest zawiera te pola:

{
  path[]: LatLng,
  samples: Number
}

Poniżej znajdziesz wyjaśnienia tych pól:

  • 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 {szerokość geograficzna,długość geograficzna} za pomocą tablicy co najmniej 2 obiektów LatLng.
  • samples (wymagany) określa liczbę punktów próbkowania wzdłuż ścieżki, dla których mają zostać zwrócone dane o wysokości. Parametr samples dzieli podaną wartość path na uporządkowany zbiór równoodległych punktów na ścieżce.

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 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 wzdłuż ścieżki, a każda próbka jest od siebie oddalona o tę samą odległość (włącznie z punktami końcowymi).

Odpowiedzi dotyczące wysokości

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

Stany wysokości

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

  • OK – oznacza, że zapytanie o usługę zostało przetworzone.
  • INVALID_REQUEST oznaczający, że zapytanie o usługę było nieprawidłowo sformułowane;
  • OVER_QUERY_LIMIT wskazujący, że osoba wysyłająca żądanie przekroczyła limit.
  • REQUEST_DENIED – usługa nie zrealizowała żądania, prawdopodobnie z powodu nieprawidłowego parametru.
  • UNKNOWN_ERROR – nieznany błąd.

Sprawdź, czy wywołanie zwrotne się powiodło, analizują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. Obiekty te zawierają te 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 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, która wskazuje maksymalną odległość między punktami danych, z których interpolowano wysokość, w metrach. Ta właściwość będzie nieobecna, jeśli rozdzielczość jest nieznana. Pamiętaj, że dane o wysokości stają się bardziej przybliżone (większe wartości resolution), gdy przekazywanych jest wiele punktów. Aby uzyskać jak najdokładniejszą wartość wysokości dla danego punktu, należy wysłać osobne zapytanie.

Przykłady wysokości

Poniższy kod tłumaczy kliknięcie mapy na żądanie wysokości przy użyciu 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 tym przykładzie tworzymy polilinię na podstawie zbioru współrzędnych i wyświetlamy dane o wysokości wzdłuż tej ścieżki za pomocą interfejsu Google Visualization API. (Ten interfejs API musisz wczytać za pomocą narzędzia Google Common Loader). Żądanie wysokości jest tworzone przy użyciu 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