Layanan Elevation

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Ringkasan

Layanan Elevation menyediakan data ketinggian untuk lokasi di permukaan bumi, termasuk lokasi kedalaman di dasar laut (yang menampilkan nilai negatif). Jika Google tidak memiliki pengukuran ketinggian yang tepat di lokasi persis yang Anda minta, layanan ini akan melakukan interpolasi dan menampilkan nilai rata-rata menggunakan empat lokasi terdekat.

Objek ElevationService memberi Anda antarmuka yang sederhana untuk membuat kueri lokasi di bumi untuk data ketinggian. Selain itu, Anda dapat meminta sampel data elevasi di sepanjang jalur, sehingga Anda dapat menghitung perubahan ketinggian yang setara di sepanjang rute. Objek ElevationService berkomunikasi dengan Layanan Ketinggian Google Maps API yang menerima permintaan ketinggian dan menampilkan data ketinggian.

Dengan layanan Elevation, Anda dapat mengembangkan aplikasi hiking dan bersepeda, aplikasi posisi seluler, atau aplikasi survei beresolusi rendah.

Memulai

Sebelum menggunakan layanan Elevation di Maps JavaScript API, pastikan terlebih dahulu bahwa Elevation API diaktifkan di Google Cloud Console, dalam project yang sama dengan yang disiapkan untuk Maps JavaScript API.

Untuk menampilkan daftar API yang telah diaktifkan:

  1. Buka Google Cloud Console.
  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:
    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 AKTIFKAN. Setelah proses 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 lebih lanjut batas harga dan penggunaan baru terkait penggunaan layanan Elevation JavaScript, lihat Penggunaan dan Penagihan untuk Elevation API.

Batas kapasitas

Perhatikan hal-hal berikut tentang batas kapasitas pada permintaan tambahan:

Batas kapasitas diterapkan per sesi pengguna, berapa pun banyaknya pengguna yang berbagi project yang sama. Saat pertama kali memuat API, Anda diberi kuota awal permintaan. Setelah Anda menggunakan kuota ini, API akan menerapkan batas kapasitas pada permintaan tambahan per detik. Jika terlalu banyak permintaan dibuat dalam jangka waktu tertentu, API akan menampilkan kode respons OVER_QUERY_LIMIT.

Batas kecepatan per sesi mencegah penggunaan layanan sisi klien untuk permintaan batch. Jika Anda ingin menghitung ketinggian untuk lokasi statis yang diketahui, gunakan layanan web 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 perlu melakukan panggilan ke server eksternal. Karena alasan tersebut, Anda harus meneruskan metode callback untuk dieksekusi setelah permintaan selesai. Metode callback ini harus memproses hasilnya. Perhatikan bahwa layanan Elevation menampilkan kode status (ElevationStatus) dan array objek ElevationResult yang terpisah.

ElevationService menangani dua jenis permintaan:

  • Permintaan untuk lokasi terpisah yang terpisah menggunakan metode getElevationForLocations(), yang menerima daftar satu atau beberapa lokasi menggunakan objek LocationElevationRequest.
  • Permintaan untuk elevasi pada serangkaian titik yang terhubung di sepanjang jalur menggunakan metode getElevationAlongPath(), yang meneruskan sekumpulan verteks jalur yang berurutan dalam objek PathElevationRequest. Saat meminta elevasi di sepanjang jalur, Anda juga harus meneruskan parameter yang menunjukkan berapa banyak sampel yang ingin diambil di 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 bumi tempat data ketinggian akan ditampilkan. Parameter ini mengambil array LatLng.

Anda dapat meneruskan beberapa koordinat dalam array, selama Anda tidak melebihi kuota layanan. Perhatikan bahwa saat meneruskan beberapa koordinat, akurasi data yang ditampilkan mungkin memiliki resolusi yang lebih rendah dibandingkan saat meminta data untuk satu koordinat.

Sampel Permintaan Elevasi Jalur

Literal objek PathElevationRequest berisi kolom-kolom berikut:

{
  path[]: LatLng,
  samples: Number
}

Bidang-bidang ini dijelaskan di bawah:

  • path (wajib) menentukan jalur di atas bumi yang akan menampilkan data ketinggian. Parameter path menentukan kumpulan dua atau lebih pasangan {lintang,bujur} yang diurutkan menggunakan array dari dua objek LatLng atau lebih.
  • samples (wajib) menentukan jumlah titik sampel di sepanjang jalur yang akan digunakan untuk menampilkan data ketinggian. Parameter samples membagi path yang diberikan menjadi sekumpulan titik yang berjarak sama di sepanjang jalur.

Seperti permintaan posisi, parameter path menentukan kumpulan nilai lintang dan bujur. Namun, tidak seperti permintaan posisi, path menentukan serangkaian verteks yang diurutkan. Daripada mengambil data elevasi di verteks, permintaan jalur diambil sampelnya sepanjang jalur, dengan setiap sampel berjarak sama antara satu sama lain (termasuk endpoint).

Respons Elevasi

Untuk setiap permintaan yang valid, layanan Elevation akan menampilkan kumpulan objek ElevationResult bersama callback 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 melebihi kuota
  • REQUEST_DENIED yang menunjukkan bahwa layanan tidak menyelesaikan permintaan, mungkin karena parameter yang tidak valid
  • UNKNOWN_ERROR menunjukkan error yang tidak diketahui

Anda harus memeriksa apakah callback berhasil dengan memeriksa kode status ini untuk 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 ketinggian lokasi dalam meter.
  • Nilai resolution, yang menunjukkan jarak maksimum antara titik data yang digunakan untuk interpolasi ketinggian, dalam meter. Properti ini akan hilang jika resolusi tidak diketahui. Perhatikan bahwa data elevasi menjadi lebih kasar (nilai resolution lebih besar) saat beberapa titik diteruskan. Untuk mendapatkan nilai elevasi yang paling akurat untuk satu titik, Anda harus mengkuerinya secara independen.

Contoh Elevasi

Kode berikut menerjemahkan klik pada peta menjadi permintaan ketinggian 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;

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;
Lihat contoh

Coba Sampel

Contoh berikut membuat polyline yang memberikan kumpulan koordinat dan menampilkan data ketinggian di sepanjang jalur tersebut menggunakan GoogleVisual 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;

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;
Lihat contoh

Coba Sampel