ภาพรวม
บริการระดับความสูงให้ข้อมูลระดับความสูงสําหรับ ตําแหน่งบนพื้นผิวโลก รวมทั้งตําแหน่งความลึกในก้นมหาสมุทร (ซึ่งจะแสดงผลค่าลบ) ในกรณีที่ Google ไม่มีการวัดระดับความสูง ณ ตําแหน่งที่แน่นอนที่คุณขอ บริการจะประมาณค่าและส่งคืนค่าเฉลี่ยโดยใช้ตําแหน่ง 4 ตําแหน่งที่ใกล้ที่สุด
วัตถุ ElevationService
มีอินเทอร์เฟซแบบง่ายสําหรับค้นหาตําแหน่งใน Earth สําหรับข้อมูลระดับความสูง นอกจากนี้ คุณยังส่งคําขอข้อมูลระดับความสูงที่สุ่มตัวอย่างตามเส้นทางได้ ซึ่งจะช่วยให้คุณคํานวณการเปลี่ยนแปลงระดับความสูงที่เทียบเท่ากันตามเส้นทางได้ วัตถุ ElevationService
สื่อสารกับบริการยกระดับ Google Maps API ที่รับคําขอระดับความสูงและส่งกลับข้อมูลระดับความสูง
ด้วยบริการการยกระดับ คุณจะพัฒนาแอปพลิเคชันเดินป่าและปั่นจักรยาน แอปพลิเคชันกําหนดตําแหน่งบนอุปกรณ์เคลื่อนที่ หรือแอปพลิเคชันสํารวจที่มีความละเอียดต่ําได้
การเริ่มต้นใช้งาน
ก่อนที่จะใช้บริการระดับความสูงใน Maps JavaScript API ให้เปิดใช้งาน Elevation API ใน Google Cloud Console ในโปรเจ็กต์เดียวกันกับที่คุณตั้งค่าไว้สําหรับ Maps JavaScript API
วิธีดูรายการ API ที่เปิดใช้
- ไปที่ Google Cloud Console
- คลิกปุ่มเลือกโปรเจ็กต์ แล้วเลือกโปรเจ็กต์เดียวกับที่คุณตั้งค่าสําหรับ Maps JavaScript API แล้วคลิกเปิด
- จากรายการ API ในหน้าแดชบอร์ด ให้มองหา Elevation API
- หากคุณเห็น API ในรายการ แสดงว่าทุกอย่างเรียบร้อยแล้ว หาก API ไม่ได้แสดงอยู่ ให้เปิดใช้
- ที่ด้านบนของหน้า ให้เลือกเปิดใช้ API เพื่อแสดงแท็บไลบรารี หรือเลือกคลังจากเมนูด้านซ้าย
- ค้นหา Elevation API แล้วเลือกจากรายการผลลัพธ์
- เลือกเปิดใช้ เมื่อประมวลผลเสร็จแล้ว 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;
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) คําขอยกระดับสร้างขึ้นโดยใช้ 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;