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

ملاحظة: المكتبات من جانب الخادم

تصف هذه الصفحة الخدمة من جانب العميل المتوفرة مع Maps JavaScript API. إذا أردت الاستعانة بخدمات الويب في "خرائط Google" على خادمك، اطّلِع على عميل Node.js لخدمات خرائط Google. وتعرض الصفحة على هذا الرابط أيضًا عميل Java وبرنامج Python وGo Client لخدمات "خرائط Google".

نظرة عامة

يمكنك أيضًا الاطّلاع على مرجع API JavaScript للخرائط: الارتفاع

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

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

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

البدء

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

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

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

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

السعر

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

السياسات

ويجب أن يتوافق استخدام خدمة Elevation مع السياسات الموضّحة لواجهة برمجة التطبيقات 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

ملاحظة: يمكنك قراءة الدليل عن استخدام TypeScript و"خرائط Google".

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

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

الاطّلاع على مثال

تجربة العينة

JSFiddle.net Google Cloud Shell

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

ملاحظة: يمكنك قراءة الدليل عن استخدام TypeScript و"خرائط Google".

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

ملاحظة: يتم تجميع JavaScript من مقتطف TypeScript.

الاطّلاع على مثال

تجربة العينة

JSFiddle.net Google Cloud Shell