نظرة عامة
توفّر خدمة الارتفاع بيانات الارتفاع للمواقع الجغرافية على سطح الأرض، بما في ذلك مواقع العمق في قاع المحيط (التي تعرض قيمًا سالبة). في الحالات التي لا تتوفّر فيها لدى Google قياسات الارتفاع بدقة في الموقع الجغرافي المحدد الذي تطلبه، سيتم إدخال الخدمة في متوسط القيمة وعرضها باستخدام المواقع الجغرافية الأربعة الأقرب.
يزوّدك الكائن ElevationService
بواجهة بسيطة للبحث عن المواقع الجغرافية على سطح الأرض لبيانات الارتفاع. بالإضافة إلى ذلك، يمكنك طلب عينات من بيانات الارتفاع على طول المسارات، ما يسمح لك بحساب تغييرات الارتفاع المكافئة على طول المسارات. يتواصل الكائن ElevationService
مع خدمة تحديد الارتفاع في "خرائط Google" التي تتلقى طلبات الارتفاع وتعرض بيانات الارتفاع.
باستخدام خدمة تحديد الارتفاع، يمكنك تطوير تطبيقات المشي لمسافات طويلة وركوب الدراجات، أو تطبيقات تحديد المواقع على الأجهزة الجوّالة، أو تطبيقات المسح منخفضة الدقة.
البدء
قبل استخدام خدمة Elevation في واجهة برمجة تطبيقات JavaScript للخرائط، تأكّد أولاً من تفعيل واجهة برمجة تطبيقات Elevation في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات JavaScript للخرائط.
لعرض قائمة بواجهات برمجة التطبيقات التي تم تمكينها:
- انتقِل إلى Google Cloud Console.
- انقر على زر اختيار مشروع، ثم حدد المشروع نفسه الذي أعددته لواجهة برمجة تطبيقات جافا سكريبت للخرائط وانقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن واجهة برمجة تطبيقات Elevation.
- إذا كنت ترى واجهة برمجة التطبيقات في القائمة، فأنت على أتم استعداد. في حال عدم إدراج واجهة برمجة التطبيقات،
يمكنك تفعيلها:
- في أعلى الصفحة، اختَر تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، اختَر المكتبة من القائمة الجانبية اليمنى.
- ابحث عن واجهة برمجة تطبيقات Elevation، ثم اختَرها من قائمة النتائج.
- اختَر تفعيل. عند انتهاء العملية، تظهر واجهة برمجة تطبيقات Elevation في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
التسعير والسياسات
السعر
اعتبارًا من 16 تموز (يوليو) 2018، تم تفعيل خطة تسعير جديدة للدفع حسب الاستخدام للخرائط والمسارات والأماكن. للاطّلاع على مزيد من المعلومات حول الحدود القصوى الجديدة للأسعار والاستخدام لاستخدام خدمة "رفع جافا سكريبت"، راجع الاستخدام والفوترة لواجهة برمجة تطبيقات Elevation API.
السياسات
يجب أن يكون استخدام خدمة Elevation متوافقًا مع السياسات الموضحة لواجهة برمجة تطبيقات Elevation.
طلبات تحديد الارتفاع
إنّ الوصول إلى خدمة Elevation غير متزامن لأنّ "واجهة برمجة التطبيقات لخرائط Google" تحتاج إلى إجراء استدعاء لخادم خارجي. لهذا السبب، يجب تمرير طريقة معاودة الاتصال
عند اكتمال الطلب. من المفترض أن تعالج طريقة رد الاتصال هذه النتيجة(النتائج). يُرجى العِلم بأنّ خدمة الارتفاع تعرض رمز حالة (ElevationStatus
) ومجموعة من كائنات ElevationResult
المنفصلة.
يعالج ElevationService
نوعين من الطلبات:
- طلبات الحصول على مواقع جغرافية منفصلة ومنفصلة باستخدام طريقة
getElevationForLocations()
، والتي يتم تمريرها إلى قائمة تضم موقعًا واحدًا أو أكثر باستخدام الكائنLocationElevationRequest
- طلبات الارتفاع على سلسلة من النقاط المتصلة على طول مسار باستخدام الطريقة
getElevationAlongPath()
، والتي تمرر مجموعة مرتبة من رؤوس المسارات ضمن كائنPathElevationRequest
. عند طلب تحديدات على طول المسارات، عليك أيضًا تمرير معلّمة تشير إلى عدد العيّنات التي تريد اتّباعها على طول هذا المسار.
ويجب أيضًا أن يجتاز كل من هذه الطرق طريقة callback لمعالجة عنصرَي ElevationResult
وElevationStatus
المعروضَين.
طلبات تحديد الموقع
يحتوي كائن LocationElevationRequest
الحرفي على الحقل التالي:
{ locations[]: LatLng }
تحدّد الخاصية locations
(مطلوبة) المواقع الجغرافية على الأرض التي يتم عرض بيانات الارتفاع منها. تتطلّب هذه المعلّمة مصفوفة من
LatLng
.
يمكنك تمرير أي عدد من الإحداثيات المتعددة في مصفوفة، شرط ألا تتجاوز حصص الخدمة. يُرجى ملاحظة أنه عند تمرير إحداثيات متعددة، قد تكون دقة أي بيانات معروضة أقل دقة من طلب بيانات إحداثية واحدة.
نماذج طلبات تحديد المسار
يحتوي الكائن الحرفي PathElevationRequest
على الحقول التالية:
{ path[]: LatLng, samples: Number }
هذه الحقول موضحة أدناه:
- يحدد
path
(مطلوب) مسارًا على الأرض مطلوب عرض بيانات الارتفاع له. تحدد المعلمةpath
مجموعة مكونة من اثنين أو أكثر من أزواج {latitude,longitude} باستخدام مصفوفة مكونة من عنصرين أو أكثر منLatLng
. 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 }, 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. (يجب تحميل واجهة برمجة التطبيقات هذه باستخدام 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 }, { 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;