خدمة الارتفاع

نظرة عامة

توفّر خدمة "الارتفاع" بيانات الارتفاع للمواقع الجغرافية على سطح الأرض، بما في ذلك المواقع الجغرافية للقاع في قاع المحيط (التي تعرِض قيمًا سالبة). في الحالات التي لا تتوفّر فيها لدى Google قياسات دقيقة للارتفاع في الموقع الجغرافي الدقيق الذي تطلبه، ستستخدم الخدمة الاستقراء لعرض قيمة متوسّطة باستخدام المواقع الجغرافية الأربعة الأقرب.

يوفّر لك عنصر ElevationService واجهة بسيطة لطلب بيانات الارتفاع من المواقع الجغرافية على الأرض. بالإضافة إلى ذلك، يمكنك طلب بيانات اتّباع عيّنات للارتفاع على طول المسارات، ما يتيح لك احتساب التغيُّرات في الارتفاع على مسافات متساوية على طول المسارات. يتواصل العنصر ElevationService مع خدمة الارتفاع في Google Maps API التي تتلقّى طلبات الارتفاع وتُرجع بيانات الارتفاع.

باستخدام خدمة "الارتفاع"، يمكنك تطوير تطبيقات للتنزّه وركوب الدراجات أو تطبيقات لتحديد المواقع الجغرافية على الأجهزة الجوّالة أو تطبيقات مسح أراضي ذات درجة دقة منخفضة.

الخطوات الأولى

قبل استخدام خدمة Elevation في Maps JavaScript API، تأكَّد أولاً من تفعيل Elevation API في Google Cloud Console، في المشروع نفسه الذي أعددته لواجهة برمجة التطبيقات Maps JavaScript API.

للاطّلاع على قائمة واجهات برمجة التطبيقات المفعَّلة:

  1. انتقِل إلى Google Cloud Console.
  2. انقر على الزر اختيار مشروع، ثم اختَر المشروع نفسه الذي أعددته لمكتبة Maps JavaScript API، ثم انقر على فتح.
  3. من قائمة واجهات برمجة التطبيقات في لوحة البيانات، ابحث عن Elevation API.
  4. إذا ظهرت لك واجهة برمجة التطبيقات في القائمة، يعني ذلك أنّك قد أكملت الخطوات اللازمة. إذا لم تكن واجهة برمجة التطبيقات مُدرَجة، فعِّلها:
    1. في أعلى الصفحة، انقر على تفعيل واجهة برمجة التطبيقات لعرض علامة التبويب المكتبة. بدلاً من ذلك، انقر على المكتبة من القائمة اليمنى.
    2. ابحث عن Elevation API، ثم اختَره من قائمة النتائج.
    3. انقر على تفعيل. عند اكتمال العملية، تظهر 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;
عرض مثال

تجربة عيّنة