Layanan Elevation

Ringkasan

Layanan Elevation menyediakan data elevasi untuk semua lokasi di permukaan bumi, termasuk lokasi kedalaman di dasar samudra (yang akan menampilkan nilai negatif). Jika Google tidak memiliki ukuran elevasi yang pasti untuk lokasi persis yang Anda minta, layanan ini akan menginterpolasi dan menampilkan nilai rata-rata menggunakan empat lokasi terdekat.

Objek ElevationService memberi Anda antarmuka sederhana untuk melakukan kueri lokasi di bumi untuk data elevasi. Selain itu, Anda juga bisa meminta sampel data elevasi beserta jalur, yang memungkinkan Anda menghitung perubahan elevasi di sepanjang rute. Objek ElevationService berkomunikasi dengan Google Maps API Elevation Service yang menerima permintaan elevasi dan menampilkan data elevasi.

Dengan layanan Elevation, Anda dapat mengembangkan aplikasi berjalan kaki dan bersepeda, aplikasi pemosisi seluler, atau aplikasi survei dengan resolusi rendah.

Memulai

Sebelum menggunakan layanan Elevation di Maps JavaScript API, pertama-tama pastikan bahwa Elevation API sudah diaktifkan di Konsol Google Cloud, dalam project yang sama dengan yang Anda siapkan untuk Maps JavaScript API.

Untuk menampilkan daftar API yang telah diaktifkan:

  1. Buka Konsol Google Cloud.
  2. Klik tombol Select a project, lalu pilih project yang sama dengan yang Anda siapkan untuk Maps JavaScript API dan klik Open.
  3. Dari daftar API di Dashboard, cari Elevation API.
  4. Jika sudah melihat API di dalam daftar, artinya Anda sudah siap. Jika API tidak tercantum, aktifkan API tersebut:
    1. Di bagian atas halaman, pilih ENABLE API untuk menampilkan tab Library. Atau, dari menu samping kiri, pilih Library.
    2. Telusuri Elevation API, lalu pilih dari daftar hasil.
    3. Pilih ENABLE. Setelah proses ini selesai, Elevation API akan muncul dalam daftar API di Dashboard.

Harga dan kebijakan

Harga

Mulai 16 Juli 2018, paket harga baru, yaitu bayar sesuai penggunaan, diberlakukan untuk Maps, Rute, dan Tempat. Untuk mempelajari harga baru dan batas penggunaan layanan Elevation JavaScript lebih lanjut, lihat Penggunaan dan Penagihan untuk Elevation API.

Kebijakan

Penggunaan layanan Elevation harus sesuai dengan kebijakan yang dijelaskan untuk Elevation API.

Permintaan Elevasi

Mengakses layanan Elevation bersifat asinkron, karena Google Maps API harus melakukan panggilan ke server eksternal. Oleh karena itu, Anda perlu meneruskan metode callback agar dieksekusi setelah permintaan diselesaikan. Metode callback ini harus memproses hasil. Perhatikan bahwa layanan Elevation menampilkan kode status (ElevationStatus) dan array objek ElevationResult yang terpisah.

ElevationService menangani dua jenis permintaan:

  • Permintaan lokasi terpisah yang berlainan menggunakan metode getElevationForLocations(), yang meneruskan daftar satu atau beberapa lokasi menggunakan objek LocationElevationRequest.
  • Permintaan elevasi pada serangkaian titik yang terhubung sepanjang jalan menggunakan metode getElevationAlongPath(), yang menerima sekumpulan verteks jalur yang diurutkan dalam objek PathElevationRequest. Saat meminta elevasi sepanjang jalur, Anda juga harus meneruskan parameter yang menunjukkan berapa banyak sampel yang ingin diambil sepanjang jalur tersebut.

Setiap metode ini juga harus meneruskan metode callback untuk menangani objek ElevationResult dan ElevationStatus yang ditampilkan.

Permintaan Elevasi Lokasi

Literal objek LocationElevationRequest berisi kolom berikut:

{
  locations[]: LatLng
}

locations (wajib) menentukan lokasi di atas bumi yang menjadi titik ditampilkannya data elevasi. Parameter ini menggunakan array LatLng.

Anda bisa meneruskan beberapa koordinat dalam sebuah array, asalkan tidak melebihi kuota layanan. Perhatikan, saat meneruskan beberapa koordinat, akurasi data yang ditampilkan mungkin memiliki resolusi lebih rendah daripada saat meminta data untuk satu koordinat.

Permintaan Sampel Elevasi Jalur

Literal objek PathElevationRequest berisi kolom berikut:

{
  path[]: LatLng,
  samples: Number
}

Kolom-kolom ini dijelaskan di bawah:

  • path (wajib) menentukan jalur di atas bumi yang data elevasinya akan ditampilkan. Parameter path menentukan kumpulan dua atau beberapa pasangan {latitude,longitude} yang diurutkan menggunakan array dari dua objek LatLng atau lebih.
  • samples (wajib) menentukan jumlah titik sampel di sepanjang jalur yang data elevasinya akan tampilkan. Parameter samples membagi path yang diberikan ke dalam kumpulan titik yang berjarak sama secara berurutan di sepanjang jalur.

Sebagaimana permintaan posisi, parameter path menetapkan sekumpulan nilai garis lintang dan garis bujur. Namun, tidak seperti permintaan posisi, path menentukan sekumpulan verteks yang diurutkan. Daripada menampilkan data elevasi di verteks, sampel permintaan jalur diambil di sepanjang jalur, dengan setiap sampel berjarak sama antara satu sama lain (termasuk endpoint).

Respons Elevasi

Untuk setiap permintaan yang valid, layanan Elevation akan mengembalikan kumpulan objek ElevationResult bersama dengan objek ElevationStatus ke callback yang ditentukan.

Status Elevasi

Setiap permintaan elevasi menampilkan kode ElevationStatus dalam fungsi callback-nya. Kode status ini akan berisi salah satu nilai berikut:

  • OK yang menunjukkan bahwa permintaan layanan berhasil
  • INVALID_REQUEST yang menunjukkan bahwa permintaan layanan memiliki format yang salah
  • OVER_QUERY_LIMIT yang menunjukkan bahwa pemohon telah melampaui kuota
  • REQUEST_DENIED yang menunjukkan bahwa layanan tidak memenuhi permintaan, mungkin karena parameter yang tidak valid
  • UNKNOWN_ERROR menunjukkan error yang tidak dikenal

Anda harus memeriksa apakah callback berhasil dengan memeriksa bahwa kode status ini OK.

Hasil Elevasi

Setelah berhasil, argumen results dari fungsi callback Anda akan berisi kumpulan objek ElevationResult. Objek ini berisi elemen berikut:

  • Elemen location (berisi objek LatLng) dari posisi penghitungan data elevasi. Perhatikan bahwa untuk permintaan jalur, kumpulan elemen location akan berisi titik sampel di sepanjang jalur.
  • Elemen elevation yang menunjukkan elevasi lokasi dalam meter.
  • Nilai resolution, yang menunjukkan jarak maksimum antara titik data yang digunakan untuk interpolasi elevasi, dalam meter. Properti ini tidak akan ada jika resolusi tidak diketahui. Perhatikan bahwa data elevasi akan menjadi kurang akurat (nilai resolution lebih besar) jika beberapa titik diteruskan. Guna memperoleh nilai elevasi yang paling akurat untuk sebuah titik, kueri terpisah harus dibuat.

Contoh Elevasi

Kode berikut menerjemahkan sebuah klik pada peta menjadi permintaan elevasi yang menggunakan objek 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
Lihat contoh

Mencoba Contoh

Contoh berikut membuat polyline yang diberi satu kumpulan koordinat dan menampilkan data elevasi sepanjang jalur tersebut menggunakan Google Visualization API. (Anda harus memuat API ini menggunakan Google Common Loader.) Permintaan elevasi dibuat menggunakan 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
Lihat contoh

Mencoba Contoh