نظرة عامة
توفّر خدمة "الارتفاع" بيانات الارتفاع للمواقع الجغرافية على سطح الأرض، بما في ذلك المواقع الجغرافية للقاع في قاع المحيط (التي تعرِض قيمًا سالبة). في الحالات التي لا تتوفّر فيها لدى Google قياسات دقيقة للارتفاع في الموقع الجغرافي الدقيق الذي تطلبه، ستستخدم الخدمة الاستقراء لعرض قيمة متوسّطة باستخدام المواقع الجغرافية الأربعة الأقرب.
يوفّر لك عنصر ElevationService
واجهة بسيطة لطلب بيانات الارتفاع
من المواقع الجغرافية على الأرض. بالإضافة إلى ذلك، يمكنك طلب بيانات اتّباع عيّنات للارتفاع على طول
المسارات، ما يتيح لك احتساب التغيُّرات في الارتفاع على مسافات متساوية
على طول المسارات. يتواصل العنصر ElevationService
مع خدمة الارتفاع في Google Maps API التي تتلقّى طلبات الارتفاع
وتُرجع بيانات الارتفاع.
باستخدام خدمة "الارتفاع"، يمكنك تطوير تطبيقات للتنزّه وركوب الدراجات أو تطبيقات لتحديد المواقع الجغرافية على الأجهزة الجوّالة أو تطبيقات مسح أراضي ذات درجة دقة منخفضة.
الخطوات الأولى
قبل استخدام خدمة Elevation في Maps JavaScript API، تأكَّد أولاً من تفعيل Elevation API في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات Maps JavaScript API.
للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة:
- انتقِل إلى Google Cloud Console.
- انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لمكتبة Maps JavaScript API، ثم انقر على فتح.
- من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Elevation API.
- إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك قد أكملت الخطوات اللازمة. إذا لم تكن واجهة برمجة التطبيقات مُدرَجة،
فعِّلها:
- في أعلى الصفحة، انقر على تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقر على المكتبة من القائمة اليمنى.
- ابحث عن Elevation API، ثم اختَره من قائمة النتائج.
- انقر على تفعيل. عند اكتمال العملية، تظهر Elevation API في قائمة واجهات برمجة التطبيقات في لوحة البيانات.
الأسعار والسياسات
التسعير
اعتبارًا من 16 تموز (يوليو) 2018، بدأ تطبيق خطة أسعار جديدة بالدفع عند الاستخدام لـ "خرائط Google" و"الطرق" و"الأماكن". للاطّلاع على مزيد من المعلومات عن الأسعار الجديدة وحدّ الاستخدام لخدمة تحديد الارتفاع باستخدام JavaScript، يُرجى الاطّلاع على الاستخدام والفوترة لواجهة برمجة التطبيقات Elevation API.
السياسات
يجب أن يكون استخدام خدمة Elevation متوافقًا مع السياسات الموضّحة في Elevation API.
طلبات الارتفاع
إنّ الوصول إلى خدمة الارتفاع غير متزامن، لأنّ واجهة برمجة التطبيقات في "خرائط Google" تحتاج إلى إجراء مكالمة إلى خادم خارجي. لهذا السبب، عليك تمرير طريقة callback
لتنفيذها عند اكتمال الطلب. من المفترض أن تعالج طريقة callback
هذه النتائج. يُرجى العِلم أنّ
خدمة الارتفاع تعرِض رمز حالة
(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
مجموعة مرتّبة من
الرؤوس. بدلاً من عرض بيانات الارتفاع في النقاط، يتم تحليل طلبات ملف المسار
على طول مسار الرحلة، حيث يكون كل قياس
متساوٍ المسافة عن الآخر (بما في ذلك نقاط النهاية).
استجابات الارتفاع
لكل طلب صالح، ستُرجع خدمة Elevation
إلى دالة الاستدعاء المحدّدة مجموعة من عناصر ElevationResult
مع عنصر ElevationStatus
.
حالات الارتفاع
يعرض كل طلب ترقية رمز ElevationStatus
ضمن دالة ردّ الاتصال. سيحتوي رمز status
هذا على إحدى القيم التالية:
OK
للإشارة إلى نجاح طلب الصيانةINVALID_REQUEST
تشير إلى أنّ طلب الخدمة كان مُشوَّهًاOVER_QUERY_LIMIT
يشير إلى أنّ مقدّم الطلب تجاوز الحصةREQUEST_DENIED
يشير ذلك إلى أنّ الخدمة لم تكتمل الطلب، على الأرجح بسبب مَعلمة غير صالحة.UNKNOWN_ERROR
تشير إلى خطأ غير معروف
عليك التحقّق من نجاح عملية معاودة الاتصال من خلال فحص رمز الحالة
هذا لـ OK
.
نتائج الارتفاع
عند نجاح العملية، ستحتوي وسيطة results
لدالة callback
على مجموعة من عناصر ElevationResult
.
تحتوي هذه العناصر على العناصر التالية:
- عنصر
location
(يحتوي على عناصرLatLng
) للموقع الجغرافي الذي يتم احتساب بيانات الارتفاع له يُرجى ملاحظة أنّه بالنسبة إلى طلبات المسارات، ستتضمّن مجموعة عناصرlocation
النقاط التي تم أخذ عيّنات منها على طول المسار. - عنصر
elevation
يشير إلى ارتفاع الموقع الجغرافي بالمتر - قيمة
resolution
، تشير إلى أقصى مسافة بين نقاط البيانات التي تمّت من خلالها الاستقراء لارتفاع السطح، بالكيلومترات لن تكون هذه السمة متوفرة إذا لم تكن درجة الدقة معروفة. يُرجى العِلم أنّه تصبح بيانات الارتفاع أكثر تقريبية (قيمresolution
أكبر) عند تمرير نقاط متعددة. للحصول على قيمة الارتفاع الأكثر دقة لنقطة معيّنة، يجب البحث عنها بشكل مستقل.
أمثلة على الارتفاع
يحوّل الرمز البرمجي التالي النقر على خريطة إلى طلب elevation
باستخدام العنصر 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. (يجب تحميل واجهة برمجة التطبيقات هذه باستخدام 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;