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