نمای کلی
سرویس Elevation دادههای ارتفاعی را برای مکانهای روی سطح زمین، از جمله مکانهای عمق در کف اقیانوس (که مقادیر منفی را برمیگردانند) ارائه میکند. در مواردی که Google اندازهگیری دقیق ارتفاع را در مکان دقیقی که درخواست میکنید ندارد، این سرویس با استفاده از چهار نزدیکترین مکان، مقدار میانگین را درونیابی کرده و برمیگرداند.
شی ElevationService
یک رابط ساده برای جستجوی مکان های روی زمین برای داده های ارتفاعی در اختیار شما قرار می دهد. علاوه بر این، میتوانید دادههای نمونهبرداری از ارتفاع را در امتداد مسیرها درخواست کنید، که به شما این امکان را میدهد تا تغییرات ارتفاعی را در طول مسیرها محاسبه کنید. شی ElevationService
با Google Maps API Elevation Service ارتباط برقرار می کند که درخواست های ارتفاع را دریافت می کند و داده های ارتفاع را برمی گرداند.
با سرویس Elevation میتوانید برنامههای پیادهروی و دوچرخهسواری، برنامههای موقعیتیابی تلفن همراه یا برنامههای نقشهبرداری با وضوح پایین را توسعه دهید.
شروع کردن
قبل از استفاده از سرویس Elevation در Maps JavaScript API، ابتدا مطمئن شوید که Elevation API در کنسول Google Cloud در همان پروژه ای که برای Maps JavaScript API تنظیم کرده اید، فعال است.
برای مشاهده لیست API های فعال:
- به کنسول Google Cloud بروید.
- روی دکمه Select a project کلیک کنید، سپس همان پروژه ای را که برای Maps JavaScript API تنظیم کرده اید انتخاب کنید و روی Open کلیک کنید.
- از لیست APIها در داشبورد ، Elevation API را جستجو کنید.
- اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
- در بالای صفحه، ENABLE API را انتخاب کنید تا تب Library نمایش داده شود. یا از منوی سمت چپ، کتابخانه را انتخاب کنید.
- Elevation API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
- ENABLE را انتخاب کنید. پس از پایان فرآیند، Elevation API در لیست APIها در داشبورد ظاهر میشود.
قیمت گذاری و سیاست ها
قیمت گذاری
از 16 ژوئیه 2018، یک طرح جدید قیمتگذاری پرداختی برای Maps، Routes و Places اجرا شد. برای کسب اطلاعات بیشتر در مورد قیمتگذاری و محدودیتهای استفاده جدید برای استفاده از سرویس JavaScript Elevation، به Usage and Billing for Elevation API مراجعه کنید.
سیاست ها
استفاده از سرویس Elevation باید مطابق با خط مشی های توضیح داده شده برای Elevation API باشد.
درخواست های ارتفاع
دسترسی به سرویس Elevation ناهمزمان است، زیرا Google Maps API باید با یک سرور خارجی تماس بگیرد. به همین دلیل، باید پس از تکمیل درخواست، یک متد برگشتی را ارسال کنید تا اجرا شود. این روش برگشتی باید نتیجه(های) را پردازش کند. توجه داشته باشید که سرویس Elevation یک کد وضعیت ( ElevationStatus
) و آرایه ای از اشیاء ElevationResult
جداگانه را برمی گرداند.
ElevationService
دو نوع درخواست را انجام می دهد:
- درخواست مکانهای مجزا و مجزا با استفاده از متد
getElevationForLocations()
، که فهرستی از یک یا چند مکان را با استفاده از یک شیLocationElevationRequest
ارسال میکند. - درخواست ارتفاع در یک سری از نقاط متصل در طول یک مسیر با استفاده از متد
getElevationAlongPath()
که مجموعه مرتبی از رئوس مسیر را در یک شیPathElevationRequest
ارسال می کند. هنگام درخواست ارتفاع در امتداد مسیرها، باید پارامتری را نیز ارسال کنید که نشان می دهد چند نمونه از آن مسیر را می خواهید بگیرید.
هر یک از این متدها همچنین باید یک متد برگشتی برای مدیریت اشیاء ElevationResult
و ElevationStatus
برگشتی ارسال کنند.
درخواست ارتفاع مکان
یک شیء LocationElevationRequest
حاوی فیلد زیر است:
{ locations[]: LatLng }
locations
(لازم) مکان(های) روی زمین را که از آن داده های ارتفاعی برگردانده می شود، تعریف می کند. این پارامتر آرایه ای از LatLng
s را می گیرد.
تا زمانی که از سهمیه خدمات تجاوز نکنید، میتوانید هر تعداد مختصات چندگانه را در یک آرایه ارسال کنید. توجه داشته باشید که هنگام ارسال چند مختصات، دقت هر داده بازگشتی ممکن است وضوح کمتری نسبت به درخواست داده برای یک مختصات داشته باشد.
نمونه درخواست ارتفاع مسیر
یک شیء PathElevationRequest
حاوی فیلدهای زیر است:
{ path[]: LatLng, samples: Number }
این فیلدها در زیر توضیح داده شده است:
-
path
(لازم) مسیری را روی زمین تعریف می کند که برای آن داده های ارتفاعی را برگرداند. پارامترpath
مجموعه ای از دو یا چند جفت مرتب شده {latitude,longitude} را با استفاده از آرایه ای از دو یا چند شیLatLng
تعریف می کند. -
samples
(الزامی) تعداد نقاط نمونه را در طول مسیری که داده های ارتفاعی برای آنها برگردانده می شود، مشخص می کند. پارامترsamples
path
داده شده را به مجموعه منظمی از نقاط مساوی در طول مسیر تقسیم می کند.
همانند درخواست های موقعیتی، پارامتر path
مجموعه ای از مقادیر طول و عرض جغرافیایی را مشخص می کند. با این حال، بر خلاف یک درخواست موقعیتی، path
مجموعه ای مرتب از رئوس را مشخص می کند. بهجای بازگشت دادههای ارتفاع در راسها، درخواستهای مسیر در طول مسیر نمونهبرداری میشوند، جایی که هر نمونه از یکدیگر فاصله دارد (شامل نقاط پایانی).
پاسخ های ارتفاعی
برای هر درخواست معتبر، سرویس Elevation مجموعه ای از اشیاء ElevationResult
را به همراه یک شی ElevationStatus
به فراخوانی تعریف شده برمی گرداند.
وضعیت های ارتفاعی
هر درخواست elevation یک کد ElevationStatus
را در تابع callback خود برمی گرداند. این کد status
شامل یکی از مقادیر زیر خواهد بود:
-
OK
نشان دهنده موفقیت آمیز بودن درخواست سرویس است -
INVALID_REQUEST
که نشان میدهد درخواست سرویس نادرست است -
OVER_QUERY_LIMIT
که نشان می دهد درخواست کننده از سهمیه فراتر رفته است -
REQUEST_DENIED
نشان می دهد که سرویس درخواست را تکمیل نکرده است، احتمالاً به دلیل وجود یک پارامتر نامعتبر -
UNKNOWN_ERROR
نشان دهنده یک خطای ناشناخته است
با بررسی این کد وضعیت برای OK
، باید بررسی کنید که پاسخ تماس شما موفق بوده است.
نتایج ارتفاع
پس از موفقیت، آرگومان results
تابع callback شما حاوی مجموعه ای از اشیاء 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;
جاوا اسکریپت
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;
Sample را امتحان کنید
مثال زیر یک چند خط با مجموعهای از مختصات میسازد و دادههای ارتفاع را در آن مسیر با استفاده از Google Visualization API نمایش میدهد. (شما باید این API را با استفاده از Google Common Loader بارگیری کنید.) یک درخواست elevation با استفاده از 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;
جاوا اسکریپت
// 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;