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