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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

نظرة عامة

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

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

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

البدء

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

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

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

التسعير والسياسات

السعر

اعتبارًا من 16 تموز (يوليو) 2018، تم إطلاق خطة جديدة لأسعار الدفع حسب الاستخدام في "خرائط Google" و"المسارات" و"الأماكن". لمزيد من المعلومات حول الحدود الجديدة للأسعار والاستخدام لاستخدام خدمة تحديد الارتفاع في JavaScript، يُرجى الاطّلاع على الاستخدام والفوترة لواجهة برمجة التطبيقات Elevation API.

السياسات

يجب أن يتوافق استخدام خدمة Elevation مع السياسات الموضّحة لواجهة برمجة تطبيقات Elevation.

طلبات الارتفاع

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

تعالج خدمة ElevationService نوعَين من الطلبات:

  • طلبات المواقع الجغرافية المنفصلة والمنفصلة باستخدام الطريقة getElevationForLocations()، والتي تمرّر قائمة بموقع واحد أو أكثر باستخدام عنصر LocationElevationRequest.
  • طلبات الارتفاع على سلسلة من النقاط المتّصلة على طول مسار باستخدام الطريقة getElevationAlongPath()، التي تمرّ بمجموعة من طلبات الترتيب المطلوبة ضمن عنصر PathElevationRequest. عند طلب الارتفاعات على المسارات، عليك أيضًا تمرير معلّمة تشير إلى عدد العيّنات التي تريد اتّباعها على طول هذا المسار.

يجب أيضًا أن ترسل كل طريقة من هذه الطرق طريقة رد اتصال للتعامل مع العناصر 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 المرئي API. (يجب تحميل واجهة برمجة التطبيقات هذه باستخدام القائم بالتحميل المشترك بين 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;
عرض مثال

جرّب عيّنة