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

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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

الأسعار

لمعرفة المزيد حول سياسات الأسعار والاستخدام لخدمة تحديد الارتفاع في JavaScript، يُرجى الاطّلاع على الاستخدام والفوترة لواجهة Elevation API.

السياسات

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

طلبات رفع مستوى الوصول

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

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

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

يجب أيضًا أن تمرّر كل طريقة من هذه الطرق طريقة رد اتصال لمعالجة عنصري 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

async function init(): Promise<void> {
    const [{ InfoWindow }, { ElevationService }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('elevation'),
    ]);

    const mapElement = document.querySelector('gmp-map')!;
    const innerMap = mapElement.innerMap;

    const elevator = new ElevationService();
    const infowindow = new InfoWindow();

    infowindow.open(innerMap);

    // Add a listener for the click event. Display the elevation for the LatLng of
    // the click inside the infowindow.
    innerMap.addListener('click', (event: google.maps.MapMouseEvent) => {
        displayLocationElevation(event.latLng!, elevator, infowindow, innerMap);
    });
}

function displayLocationElevation(
    location: google.maps.LatLng,
    elevator: google.maps.ElevationService,
    infowindow: google.maps.InfoWindow,
    map: google.maps.Map
) {
    // Format numeric values to two decimal places
    const formatter = new Intl.NumberFormat(undefined, {
        maximumFractionDigits: 2,
    });

    // Initiate the location request
    elevator
        .getElevationForLocations({
            locations: [location],
        })
        .then(({ results }) => {
            if (results[0]) {
                const { elevation, location: resultLocation } = results[0];
                infowindow.setPosition(resultLocation);
                infowindow.setContent(
                    `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.`
                );
            } else {
                infowindow.setPosition(location);
                infowindow.setContent('No results found');
            }

            infowindow.open(map);
        })
        .catch((e: unknown) => {
            infowindow.setContent(
                `Elevation service failed due to: ${String(e)}`
            );
        });
}

void init();
index.ts

ملاحظة: يُرجى قراءة الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

async function init() {
    const [{ InfoWindow }, { ElevationService }] = await Promise.all([
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('elevation'),
    ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    const elevator = new ElevationService();
    const infowindow = new InfoWindow();

    infowindow.open(innerMap);

    // Add a listener for the click event. Display the elevation for the LatLng of
    // the click inside the infowindow.
    innerMap.addListener('click', (event) => {
        displayLocationElevation(event.latLng, elevator, infowindow, innerMap);
    });
}

function displayLocationElevation(location, elevator, infowindow, map) {
    // Format numeric values to two decimal places
    const formatter = new Intl.NumberFormat(undefined, {
        maximumFractionDigits: 2,
    });

    // Initiate the location request
    elevator
        .getElevationForLocations({
            locations: [location],
        })
        .then(({ results }) => {
            if (results[0]) {
                const { elevation, location: resultLocation } = results[0];
                infowindow.setPosition(resultLocation);
                infowindow.setContent(
                    `The elevation at ${String(resultLocation)} <br>is ${formatter.format(elevation)} meters.`
                );
            } else {
                infowindow.setPosition(location);
                infowindow.setContent('No results found');
            }

            infowindow.open(map);
        })
        .catch((e) => {
            infowindow.setContent(
                `Elevation service failed due to: ${String(e)}`
            );
        });
}

void init();
index.js

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

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

ملاحظة: يُرجى قراءة الدليل حول استخدام 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 }, // 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

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

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