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

نظرة عامة

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

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

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

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

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

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

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

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

التسعير

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

السياسات

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

طلبات رفع أثقال

الوصول إلى خدمة تحديد الارتفاع غير متزامن، نظرًا تحتاج واجهة برمجة التطبيقات لخرائط 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;
index.ts

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;
index.js
الاطّلاع على مثال

تجربة "عيّنة"

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

تجربة "عيّنة"