ภาพรวม
บริการ Elevation จะให้ข้อมูลระดับความสูงของสถานที่ต่างๆ บนพื้นผิวโลก รวมถึงความลึกของสถานที่ต่างๆ ที่ก้นมหาสมุทร (ซึ่งจะแสดงผลเป็นค่าลบ) ในกรณีที่ Google ไม่มีค่าการวัดระดับความสูงที่แน่นอนในตำแหน่งที่คุณขอ บริการจะประมาณค่าและแสดงผลค่าเฉลี่ยโดยใช้ตำแหน่งที่ใกล้ที่สุด 4 ตำแหน่ง
ออบเจ็กต์ ElevationService มีอินเทอร์เฟซที่เรียบง่ายในการค้นหาตำแหน่งบนโลกเพื่อดูข้อมูลระดับความสูง นอกจากนี้ คุณยังขอข้อมูลระดับความสูงที่สุ่มตัวอย่างตามเส้นทางได้ด้วย ซึ่งจะช่วยให้คุณคำนวณการเปลี่ยนแปลงระดับความสูงที่เท่ากันตามเส้นทางได้ ออบเจ็กต์ ElevationService จะสื่อสารกับบริการระดับความสูงของ Google Maps API ซึ่งรับคำขอระดับความสูงและแสดงผลข้อมูลระดับความสูง
บริการระดับความสูงช่วยให้คุณพัฒนาแอปพลิเคชันการเดินป่าและการปั่นจักรยาน แอปพลิเคชันการระบุตำแหน่งบนอุปกรณ์เคลื่อนที่ หรือแอปพลิเคชันการสำรวจความละเอียดต่ำได้
เริ่มต้นใช้งาน
ก่อนใช้บริการระดับความสูงใน Maps JavaScript API ให้ตรวจสอบก่อนว่าได้เปิดใช้ Elevation API ในคอนโซล Google Cloud ในโปรเจ็กต์เดียวกับที่คุณตั้งค่าไว้สำหรับ Maps JavaScript API
วิธีดูรายการ API ที่เปิดใช้
- ไปที่ คอนโซล Google Cloud
- คลิกปุ่มเลือกโปรเจ็กต์ แล้วเลือกโปรเจ็กต์เดียวกับที่ตั้งค่าไว้สำหรับ Maps JavaScript API แล้วคลิกเปิด
- จากรายการ API ในแดชบอร์ด ให้มองหา Elevation API
- หากเห็น API ในรายการ แสดงว่าทุกอย่างเรียบร้อยแล้ว หาก API ไม่แสดงในรายการ ให้เปิดใช้โดยทำดังนี้
- ที่ด้านบนของหน้า ให้เลือกเปิดใช้ API เพื่อแสดงแท็บคลัง หรือเลือกคลังจากเมนูด้านซ้าย
- ค้นหา Elevation API แล้วเลือกจากรายการผลลัพธ์
- เลือกเปิดใช้ เมื่อกระบวนการเสร็จสิ้น Elevation API จะปรากฏในรายการ API บนแดชบอร์ด
ราคาและนโยบาย
ราคา
หากต้องการดูข้อมูลเกี่ยวกับนโยบายราคาและการใช้งานสำหรับบริการ JavaScript Elevation โปรดดูการใช้งานและการเรียกเก็บเงินสำหรับ Elevation API
นโยบาย
การใช้บริการ Elevation ต้องเป็นไปตามนโยบายที่อธิบายไว้สำหรับ Elevation API
คำขอการยกระดับ
การเข้าถึงบริการระดับความสูงเป็นแบบอะซิงโครนัส เนื่องจาก Google Maps API ต้องเรียกใช้เซิร์ฟเวอร์ภายนอก ด้วยเหตุนี้ คุณจึงต้องส่งเมธอด callback เพื่อดำเนินการเมื่อคำขอเสร็จสมบูรณ์ เมธอด Callback นี้ควรประมวลผลผลลัพธ์ โปรดทราบว่าบริการ Elevation จะแสดงรหัสสถานะ (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 ไปยัง Callback ที่กำหนดไว้
สถานะการยกระดับ
คำขอระดับความสูงแต่ละรายการจะแสดงรหัส ElevationStatus ภายในฟังก์ชัน Callback รหัส status นี้จะมีค่าใดค่าหนึ่งต่อไปนี้
OKซึ่งบ่งบอกว่าคำขอบริการสำเร็จแล้วINVALID_REQUESTซึ่งระบุว่าคำขอบริการมีรูปแบบไม่ถูกต้องOVER_QUERY_LIMITซึ่งระบุว่าผู้ขอใช้เกินโควต้าแล้วREQUEST_DENIEDซึ่งระบุว่าบริการดำเนินการตามคำขอไม่เสร็จสมบูรณ์ โดยอาจเป็นเพราะพารามิเตอร์ไม่ถูกต้องUNKNOWN_ERRORซึ่งระบุข้อผิดพลาดที่ไม่ทราบสาเหตุ
คุณควรตรวจสอบว่า Callback สำเร็จหรือไม่โดยดูรหัสสถานะนี้สำหรับ OK
ผลลัพธ์ระดับความสูง
เมื่อดำเนินการสำเร็จ อาร์กิวเมนต์ results ของฟังก์ชัน Callback จะมีชุดออบเจ็กต์ ElevationResult
ออบเจ็กต์เหล่านี้ประกอบด้วยองค์ประกอบต่อไปนี้
- องค์ประกอบ
location(มีออบเจ็กต์LatLng) ของตำแหน่งที่กำลังคำนวณข้อมูลระดับความสูง โปรดทราบว่าสำหรับคำขอเส้นทาง ชุดองค์ประกอบlocationจะมีจุดตัวอย่างตามเส้นทาง - องค์ประกอบ
elevationที่ระบุระดับความสูงของสถานที่ในหน่วยเมตร - ค่า
resolutionซึ่งระบุระยะทางสูงสุดระหว่างจุดข้อมูลที่ใช้ประมาณค่าระดับความสูงในหน่วยเมตร พร็อพเพอร์ตี้นี้จะหายไปหากไม่ทราบความละเอียด โปรดทราบว่าข้อมูลระดับความสูงจะมีความละเอียดน้อยลง (ค่าresolutionมากขึ้น) เมื่อมีการส่งผ่านจุดหลายจุด หากต้องการรับค่าระดับความสูงที่แม่นยำที่สุดสำหรับจุดหนึ่งๆ คุณควรค้นหาจุดนั้นแยกต่างหาก
ตัวอย่างระดับความสูง
โค้ดต่อไปนี้จะแปลการคลิกบนแผนที่เป็นคำขอระดับความสูงโดยใช้ออบเจ็กต์ LocationElevationRequest
TypeScript
async function init(): Promise<void> { const [{ InfoWindow }, { ElevationService }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('elevation'), ]); const mapElement = document.querySelector('gmp-map')!; const innerMap = mapElement.innerMap; const elevator = new ElevationService(); const infowindow = new InfoWindow(); infowindow.open(innerMap); // Add a listener for the click event. Display the elevation for the LatLng of // the click inside the infowindow. innerMap.addListener('click', (event: google.maps.MapMouseEvent) => { displayLocationElevation(event.latLng!, elevator, infowindow, innerMap); }); } function displayLocationElevation( location: google.maps.LatLng, elevator: google.maps.ElevationService, infowindow: google.maps.InfoWindow, map: google.maps.Map ) { // Format numeric values to two decimal places const formatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2, }); // Initiate the location request elevator .getElevationForLocations({ locations: [location], }) .then(({ results }) => { if (results[0]) { const { elevation, location: resultLocation } = results[0]; infowindow.setPosition(resultLocation); infowindow.setContent( `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.` ); } else { infowindow.setPosition(location); infowindow.setContent('No results found'); } infowindow.open(map); }) .catch((e: unknown) => { infowindow.setContent( `Elevation service failed due to: ${String(e)}` ); }); } void init();
JavaScript
async function init() { const [{ InfoWindow }, { ElevationService }] = await Promise.all([ google.maps.importLibrary('maps'), google.maps.importLibrary('elevation'), ]); const mapElement = document.querySelector('gmp-map'); const innerMap = mapElement.innerMap; const elevator = new ElevationService(); const infowindow = new InfoWindow(); infowindow.open(innerMap); // Add a listener for the click event. Display the elevation for the LatLng of // the click inside the infowindow. innerMap.addListener('click', (event) => { displayLocationElevation(event.latLng, elevator, infowindow, innerMap); }); } function displayLocationElevation(location, elevator, infowindow, map) { // Format numeric values to two decimal places const formatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2, }); // Initiate the location request elevator .getElevationForLocations({ locations: [location], }) .then(({ results }) => { if (results[0]) { const { elevation, location: resultLocation } = results[0]; infowindow.setPosition(resultLocation); infowindow.setContent( `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.` ); } else { infowindow.setPosition(location); infowindow.setContent('No results found'); } infowindow.open(map); }) .catch((e) => { infowindow.setContent( `Elevation service failed due to: ${String(e)}` ); }); } void init();
ตัวอย่างต่อไปนี้สร้างเส้นประกอบโดยใช้ชุดพิกัดและแสดงข้อมูลระดับความสูงตามเส้นทางนั้นโดยใช้
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;