บริการลิฟต์

หมายเหตุ: ไลบรารีฝั่งเซิร์ฟเวอร์

หน้านี้อธิบายถึงบริการฝั่งไคลเอ็นต์ที่ให้บริการด้วย Maps JavaScript API ถ้าคุณต้องการทํางานกับบริการเว็บของ Google Maps บนเซิร์ฟเวอร์ โปรดดูที่ไคลเอ็นต์ Node.js สําหรับบริการ Google Maps นอกจากนี้ หน้าที่ลิงก์ดังกล่าวยังแนะนําไคลเอ็นต์ Java, ไคลเอ็นต์ Python และ Go สําหรับบริการ Google Maps อีกด้วย

ภาพรวม

โปรดดูข้อมูลอ้างอิง Maps JavaScript API ด้วย ระดับความสูง

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

วัตถุ ElevationService มีอินเทอร์เฟซแบบง่ายสําหรับค้นหาตําแหน่งใน Earth สําหรับข้อมูลระดับความสูง นอกจากนี้ คุณยังส่งคําขอข้อมูลระดับความสูงที่สุ่มตัวอย่างตามเส้นทางได้ ซึ่งจะช่วยให้คุณคํานวณการเปลี่ยนแปลงระดับความสูงที่เทียบเท่ากันตามเส้นทางได้ วัตถุ ElevationService สื่อสารกับบริการยกระดับ Google Maps 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 โปรดดูการใช้งานและการเรียกเก็บเงินสําหรับ 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 จะกําหนดชุดคู่ {latitude,longitude} ที่เรียงลําดับสองชุดขึ้นไปโดยใช้อาร์เรย์ของออบเจ็กต์ 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 ที่ใหญ่ขึ้น) เมื่อผ่านการตรวจสอบหลายจุด หากต้องการหาค่าระดับความสูงที่แม่นยําที่สุด ณ จุดใดจุดหนึ่ง คุณควรค้นหาค่าแยกต่างหาก

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

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

หมายเหตุ: อ่านคู่มือเกี่ยวกับการใช้ TypeScript และ Google Maps

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;
index.js

หมายเหตุ: JavaScript ได้รับการคอมไพล์จากข้อมูลโค้ด TypeScript

ดูตัวอย่าง

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

JSFiddle.net CodeSandbox.io Google Cloud Shell

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

หมายเหตุ: อ่านคู่มือเกี่ยวกับการใช้ TypeScript และ Google Maps

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;
index.js

หมายเหตุ: JavaScript ได้รับการคอมไพล์จากข้อมูลโค้ด TypeScript

ดูตัวอย่าง

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

JSFiddle.net CodeSandbox.io Google Cloud Shell