บริการลิฟต์

ภาพรวม

บริการระดับความสูงให้ข้อมูลระดับความสูงสำหรับตำแหน่งบนพื้นผิวโลก รวมถึงตำแหน่งความลึกบนก้นมหาสมุทร (ซึ่งแสดงค่าลบ) ในกรณีที่ Google ไม่ได้วัดระดับความสูงที่แน่นอนตามตําแหน่งที่คุณขอ บริการจะประมาณค่าและแสดงผลเฉลี่ยโดยใช้ตําแหน่งที่ใกล้เคียงที่สุด 4 แห่ง

ออบเจ็กต์ ElevationService มีอินเทอร์เฟซที่เรียบง่ายให้คุณค้นหาตำแหน่งบนโลกสำหรับข้อมูลระดับความสูง นอกจากนี้ คุณอาจขอข้อมูลระดับความสูงจากการสุ่มตัวอย่างตลอดเส้นทาง ซึ่งจะช่วยให้คำนวณการเปลี่ยนแปลงระดับความสูงที่เท่ากันตลอดเส้นทางได้ ออบเจ็กต์ ElevationService สื่อสารกับบริการระดับความสูงของ Google Maps API ซึ่งได้รับคำขอระดับความสูงและส่งคืนข้อมูลระดับความสูง

เมื่อใช้บริการระดับความสูง คุณสามารถพัฒนาแอปพลิเคชันการเดินป่าและปั่นจักรยาน แอปพลิเคชันการกำหนดตำแหน่งบนอุปกรณ์เคลื่อนที่ หรือแอปพลิเคชันการสำรวจที่มีความละเอียดต่ำ

เริ่มต้นใช้งาน

ก่อนที่จะใช้บริการ Elevation ใน Maps JavaScript API ก่อนอื่นให้เปิดใช้ Elevation API ใน Google Cloud Console ในโปรเจ็กต์เดียวกับที่คุณตั้งค่าไว้สําหรับ Maps JavaScript API

วิธีดูรายการ API ที่เปิดใช้

  1. ไปที่ Google Cloud Console
  2. คลิกปุ่มเลือกโปรเจ็กต์ จากนั้นเลือกโปรเจ็กต์เดียวกับที่คุณตั้งค่าสำหรับ Maps JavaScript API แล้วคลิกเปิด
  3. จากรายการ API ในหน้าแดชบอร์ด ให้มองหา Elevation API
  4. หากเห็น API ในรายการ นั่นหมายความว่าทุกอย่างเรียบร้อยแล้ว หาก API ไม่อยู่ในรายการ ให้เปิดใช้งานโดยทำดังนี้
    1. เลือกเปิดใช้ API ที่ด้านบนของหน้าเพื่อแสดงแท็บไลบรารี หรือเลือกคลังจากเมนูด้านซ้าย
    2. ค้นหา Elevation API แล้วเลือกจากรายการผลลัพธ์
    3. เลือกเปิดใช้ เมื่อขั้นตอนเสร็จสิ้นแล้ว Elevation API จะปรากฏในรายการ API ในหน้าแดชบอร์ด

ราคาและนโยบาย

การกำหนดราคา

นับตั้งแต่วันที่ 16 กรกฎาคม 2018 แผนการตั้งราคาแบบใหม่แบบจ่ายเมื่อใช้ได้มีผลกับ Maps, Routes และ Places หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับการกำหนดราคาและขีดจำกัดการใช้งานใหม่สำหรับการใช้บริการ JavaScript Elevation ของคุณ โปรดดูการใช้งานและการเรียกเก็บเงินสำหรับ Elevation API

นโยบาย

การใช้บริการระดับความสูงต้องเป็นไปตามนโยบายที่อธิบายไว้สำหรับ Elevation API

คำขอยกระดับ

การเข้าถึงบริการระดับความสูงไม่พร้อมกัน เนื่องจาก Google Maps API ต้องเรียกไปยังเซิร์ฟเวอร์ภายนอก ด้วยเหตุนี้ คุณจึงต้องส่งเมธอด callback เพื่อดําเนินการเมื่อคําขอเสร็จสมบูรณ์ วิธีเรียกกลับนี้ควรประมวลผลผลลัพธ์ โปรดทราบว่าบริการยกระดับจะแสดงรหัสสถานะ (ElevationStatus) และอาร์เรย์ของออบเจ็กต์ ElevationResult ที่แยกกัน

ElevationService จัดการกับคำขอ 2 ประเภทดังนี้

  • คำขอตำแหน่งแยกกันและแยกกันโดยใช้เมธอด getElevationForLocations() ซึ่งส่งผ่านรายการตำแหน่งอย่างน้อย 1 แห่งโดยใช้ออบเจ็กต์ LocationElevationRequest
  • คำขอระดับความสูงของชุดจุดที่เชื่อมต่อตลอดเส้นทางโดยใช้เมธอด getElevationAlongPath() ซึ่งส่งผ่านชุดจุดยอดมุมของเส้นทางตามลำดับภายในออบเจ็กต์ PathElevationRequest เมื่อขอระดับความสูงตลอดเส้นทาง คุณต้องส่งพารามิเตอร์ที่ระบุจำนวนตัวอย่างที่คุณต้องการใช้ในเส้นทางนั้นด้วย

โดยแต่ละเมธอดจะต้องผ่านเมธอด callback เพื่อจัดการออบเจ็กต์ ElevationResult และ ElevationStatus ที่แสดงผลด้วย

คำขอระดับความสูงของสถานที่

ลิเทอรัลออบเจ็กต์ LocationElevationRequest มีช่องต่อไปนี้

{
  locations[]: LatLng
}

locations (ต้องระบุ) ระบุตำแหน่งบนพื้นโลกที่จะแสดงข้อมูลระดับความสูง พารามิเตอร์นี้รับอาร์เรย์ LatLng วินาที

คุณจะส่งพิกัดหลายรายการภายในอาร์เรย์กี่รายการก็ได้ ตราบใดที่ไม่เกินโควต้าของบริการ โปรดทราบว่าเมื่อส่งผ่านพิกัดหลายพิกัด ข้อมูลที่ส่งคืนอาจมีความละเอียดน้อยกว่าเมื่อ ขอข้อมูลสำหรับพิกัดเดียว

คำขอการยกระดับเส้นทางตัวอย่าง

ออบเจ็กต์ลิเทอรัล PathElevationRequest มีช่องต่อไปนี้

{
  path[]: LatLng,
  samples: Number
}

ฟิลด์เหล่านี้มีคำอธิบายอยู่ด้านล่าง:

  • path (ต้องระบุ) กำหนดเส้นทางบนพื้นโลกที่จะแสดงข้อมูลระดับความสูง พารามิเตอร์ path จะกำหนดชุดคู่ {ละติจูด,ลองจิจูด} ที่มีลำดับตั้งแต่ 2 คู่ขึ้นไปโดยใช้อาร์เรย์ของออบเจ็กต์ LatLng อย่างน้อย 2 รายการ
  • samples (ต้องระบุ) ระบุจำนวนจุดตัวอย่างบนเส้นทางที่จะแสดงผลข้อมูลระดับความสูง พารามิเตอร์ samples จะแบ่ง path ที่กำหนดเป็นชุดของจุดที่มีขนาดเท่าๆ กันตามเส้นทาง

พารามิเตอร์ path จะระบุชุดค่าละติจูดและลองจิจูดเช่นเดียวกับคำขอตามตำแหน่ง แต่ path จะระบุชุดของจุดยอดที่เรียงลำดับแล้ว ซึ่งต่างจากคำขอตามตำแหน่ง แทนที่จะส่งคืนข้อมูลระดับความสูงที่จุดยอด ระบบจะสุ่มตัวอย่างคำขอเส้นทางตามความยาวของเส้นทาง โดยที่ตัวอย่างแต่ละรายการจะเว้นระยะห่างจากกัน (รวมถึงปลายทางด้วย)

คำตอบเกี่ยวกับการยกระดับ

สำหรับคำขอที่ถูกต้องแต่ละรายการ บริการระดับความสูงจะส่งกลับชุดออบเจ็กต์ ElevationResult ไปยังโค้ดเรียกกลับที่ระบุไว้ รวมถึงออบเจ็กต์ ElevationStatus

สถานะระดับความสูง

คำขอการยกระดับแต่ละรายการจะแสดงโค้ด ElevationStatus ภายในฟังก์ชันเรียกกลับ โค้ด status นี้จะมีค่าใดค่าหนึ่งต่อไปนี้

  • OK ระบุว่าส่งคำขอบริการสำเร็จแล้ว
  • INVALID_REQUEST ซึ่งแสดงว่าคำขอบริการมีรูปแบบไม่ถูกต้อง
  • OVER_QUERY_LIMIT ซึ่งแสดงว่าผู้ขอใช้โควต้าเกิน
  • REQUEST_DENIED ซึ่งระบุว่าบริการไม่ได้ดำเนินการตามคำขอ ซึ่งน่าจะเป็นเพราะพารามิเตอร์ไม่ถูกต้อง
  • UNKNOWN_ERROR บ่งบอกว่าเกิดข้อผิดพลาดที่ไม่ทราบสาเหตุ

คุณควรตรวจสอบว่าโค้ดเรียกกลับทำงานสำเร็จโดยการตรวจสอบรหัสสถานะนี้สำหรับ OK

ผลลัพธ์การยกระดับ

เมื่อทำสำเร็จ อาร์กิวเมนต์ results ของฟังก์ชันเรียกกลับจะมีชุดออบเจ็กต์ ElevationResult รายการ วัตถุเหล่านี้มีองค์ประกอบต่อไปนี้:

  • องค์ประกอบ location (มีออบเจ็กต์ LatLng) ของตำแหน่งที่มีการคํานวณข้อมูลระดับความสูง โปรดทราบว่าสำหรับคำขอเส้นทาง ชุดขององค์ประกอบ location จะมีจุดที่ถูกสุ่มตัวอย่างตลอดเส้นทาง
  • องค์ประกอบ elevation ที่ระบุระดับความสูงของสถานที่เป็นเมตร
  • ค่า resolution ซึ่งระบุระยะทางสูงสุดระหว่างจุดข้อมูลที่มีการประมาณค่าระดับความสูงเป็นเมตร โดยพร็อพเพอร์ตี้นี้จะหายไปหากไม่ทราบวิธีแก้ปัญหา โปรดทราบว่าข้อมูลระดับความสูงจะหยาบยิ่งขึ้น (ค่า resolution ที่ใหญ่ขึ้น) เมื่อมีการส่งผ่านหลายจุด หากต้องการได้ค่าระดับความสูงที่แม่นยำที่สุดสำหรับจุดๆ หนึ่ง ควรค้นหาค่าดังกล่าวอย่างอิสระ

ตัวอย่างระดับความสูง

โค้ดต่อไปนี้จะแปลการคลิกบนแผนที่เป็นคำขอระดับความสูงโดยใช้ออบเจ็กต์ 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;
ดูตัวอย่าง

ลองใช้ตัวอย่าง

ตัวอย่างต่อไปนี้สร้างโพลีไลน์ที่กำหนดชุดพิกัดและแสดงข้อมูลระดับความสูงตลอดเส้นทางนั้นโดยใช้ Google Visualization API (คุณต้องโหลด API นี้โดยใช้ Google Common Loader) คำขอยกระดับสร้างขึ้นโดยใช้ 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;
ดูตัวอย่าง

ลองใช้ตัวอย่าง