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

نظرة عامة

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

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

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

البدء

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

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

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

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;
index.js
عرض مثال

تجربة عيّنة من المحتوى

ينشئ المثال التالي سطرًا متعددًا مع إضافة مجموعة من الإحداثيات ويعرض بيانات الارتفاع على طول هذا المسار باستخدام واجهة برمجة تطبيقات العرض المرئي من 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;
index.ts

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;
index.js
عرض مثال

تجربة عيّنة من المحتوى