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

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

نظرة عامة

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

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

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

البدء

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

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

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

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

السعر

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

السياسات

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

طلبات تحديد الارتفاع

إنّ الوصول إلى خدمة Elevation غير متزامن لأنّ "واجهة برمجة التطبيقات لخرائط Google" تحتاج إلى إجراء استدعاء لخادم خارجي. لهذا السبب، يجب تمرير طريقة معاودة الاتصال عند اكتمال الطلب. من المفترض أن تعالج طريقة رد الاتصال هذه النتيجة(النتائج). يُرجى العِلم بأنّ خدمة الارتفاع تعرض رمز حالة (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 مجموعة من الرؤوس مرتَّبة. بدلاً من عرض بيانات الارتفاع في الرؤوس، يتم أخذ عينات من طلبات المسار على طول المسار، حيث تكون المسافة بين كل نموذج والأخرى متساوية من ناحية بعضها البعض (بما في ذلك نقاط النهاية).

استجابات الارتفاع

بالنسبة إلى كل طلب صالح، ستعود خدمة "الارتفاع" إلى معاودة الاتصال المحدّدة مجموعة من عناصر 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 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;
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
عرض مثال

تجربة النموذج