บริการลิฟต์

ภาพรวม

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

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

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

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

ก่อนใช้บริการระดับความสูงใน 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 API

นโยบาย

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

คำขอยกระดับ

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

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

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

วิธีการแต่ละวิธีเหล่านี้จะต้องผ่านการเรียกกลับ ในการจัดการ ElevationResult ที่แสดงผล และ ElevationStatus ออบเจ็กต์

คำขอยกระดับสถานที่

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

{
  locations[]: LatLng
}

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

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

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

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

{
  path[]: LatLng,
  samples: Number
}

ฟิลด์เหล่านี้จะอธิบายไว้ด้านล่าง

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

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

การตอบกลับระดับความสูง

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

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

คำขอยกระดับแต่ละรายการแสดงรหัส ElevationStatus ภายในฟังก์ชัน Callback รหัส 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 }, // 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;
ดูตัวอย่าง

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

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

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