سرویس ارتفاع

توجه: کتابخانه‌های سمت سرور

این صفحه سرویس سمت کارخواه را که با Maps JavaScript API دردسترس است شرح می‌دهد. اگر می‌خواهید با سرویس‌های وب Google Maps در سرورتان کار کنید، به Node.js Client for Google Maps Services نگاهی بیندازید. صفحه موجود در آن پیوند همچنین Java Client،‏ Python Client، و Go Client را برای «خدمات Google Maps» معرفی می‌کند.

نمای کلی

همچنین به «مرجع میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps» مراجعه کنید: ارتفاع

سرویس «ارتفاع» داده‌های ارتفاع را برای مکان‌های روی سطح زمین، ازجمله مکان‌های عمیق در کف اقیانوس (که مقادیر منفی برمی‌گردانند)، ارائه می‌دهد. در مواردی که Google اندازه‌گیری‌های دقیق ارتفاع را در مکان دقیقی که درخواست می‌کنید نداشته باشد، سرویس بااستفاده از چهار مکان نزدیک، مقدار میانگین را درون‌یابی و برمی‌گرداند.

شیء ElevationService میانای ساده‌ای برای پرسمان مکان‌ها در زمین برای داده‌های ارتفاع در اختیار شما قرار می‌دهد. علاوه‌براین، می‌توانید داده‌های ارتفاع نمونه‌برداری‌شده را درطول مسیرها درخواست کنید، که به شما امکان می‌دهد تغییرات ارتفاع با فاصله مساوی را درطول مسیرها محاسبه کنید. شیء ElevationService با «سرویس ارتفاع Google Maps API» که درخواست‌های ارتفاع را دریافت می‌کند و داده‌های ارتفاع را برمی‌گرداند، ارتباط برقرار می‌کند.

با سرویس «ارتفاع»، می‌توانید برنامه‌های پیاده‌روی و دوچرخه‌سواری، برنامه‌های موقعیت‌یابی تلفن همراه، یا برنامه‌های نقشه‌برداری با وضوح پایین را توسعه دهید.

درحال شروع کردن

قبل‌از استفاده از سرویس Elevation در Maps JavaScript API، ابتدا مطمئن شوید که Elevation API در کنسول Google Cloud، در همان پروژه‌ای که برای Maps JavaScript API راه‌اندازی کرده‌اید، فعال شده باشد.

برای مشاهده فهرست میاناهای برنامه‌سازی کاربردی فعال‌شده:

1. به کنسول Google Cloud بروید.
2. روی دکمه انتخاب پروژه کلیک کنید، سپس همان پروژه‌ای را که برای Maps JavaScript API راه‌اندازی کرده‌اید انتخاب کنید و روی باز کردن کلیک کنید.
3. از فهرست میاناهای برنامه‌سازی کاربردی در داشبورد، Elevation API را پیدا کنید.
4. اگر API را در فهرست می‌بینید، همه چیز آماده است. اگر میانای برنامه‌سازی کاربردی در فهرست نیست، آن را فعال کنید:
   1. در بالای صفحه، فعال کردن API را انتخاب کنید تا برگه کتابخانه نمایش داده شود. یا از منوِ سمت راست، کتابخانه را انتخاب کنید.
   2. Elevation API را جستجو کنید، سپس آن را از فهرست نتایج انتخاب کنید.
   3. فعال کردن را انتخاب کنید. وقتی فرایند تمام شد، Elevation API در فهرست میاناهای برنامه‌سازی کاربردی در داشبورد نشان داده می‌شود.

قیمت‌گذاری و خط‌مشی‌ها

قیمت‌گذاری

برای آشنایی با خط‌مشی‌های قیمت‌گذاری و استفاده از سرویس Elevation جاوا اسکریپت، استفاده و صورت‌حساب را برای Elevation API ببینید.

خط‌مشی‌ها

استفاده از سرویس Elevation باید مطابق با خط‌مشی‌های شرح‌داده‌شده برای Elevation API باشد.

درخواست‌های ارتقا

دسترسی به سرویس «ارتفاع» ناهمگام است، زیرا Google Maps API باید با سرور خارجی تماس برقرار کند. به همین دلیل، باید روش فراخوانی را برای اجرا پس‌از تکمیل درخواست ارسال کنید. این روش فراخوانی باید نتیجه(ها) را پردازش کند. توجه داشته باشید که سرویس Elevation یک کد وضعیت (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 مجموعه‌ای مرتب از رئوس را مشخص می‌کند. به‌جای برگرداندن داده‌های ارتفاع در رأس‌ها، درخواست‌های مسیر درطول مسیر نمونه‌برداری می‌شوند، که در آن هر نمونه از نمونه دیگر فاصله یکسانی دارد (شامل نقاط پایانی).

پاسخ‌های ارتقا

برای هر درخواست معتبر، سرویس Elevation مجموعه‌ای از اشیاء 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 Maps را بخوانید.

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 نمایش می‌دهد. (باید این 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 Maps را بخوانید.

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

توجه: جاوا اسکریپت از قطعه TypeScript کامپایل شده است.

مشاهده نمونه