سرویس ارتفاع

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

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

نمای کلی

همچنین به مرجع API جاوا اسکریپت نقشه‌ها مراجعه کنید: ارتفاع

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

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

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

شروع به کار

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

برای مشاهده لیست API های فعال خود:

1. به کنسول گوگل کلود بروید.
2. روی دکمه‌ی «انتخاب پروژه» کلیک کنید، سپس همان پروژه‌ای را که برای Maps JavaScript API تنظیم کرده‌اید، انتخاب کنید و روی «باز کردن» کلیک کنید.
3. از لیست APIهای موجود در داشبورد ، به دنبال Elevation API بگردید.
4. اگر API را در لیست مشاهده کردید، همه چیز آماده است. اگر API در لیست نیست ، آن را فعال کنید:
   1. در بالای صفحه، گزینه‌ی ENABLE API را انتخاب کنید تا تب کتابخانه نمایش داده شود. همچنین می‌توانید از منوی سمت چپ، گزینه‌ی کتابخانه را انتخاب کنید.
   2. عبارت Elevation API را جستجو کنید، سپس آن را از لیست نتایج انتخاب کنید.
   3. گزینه فعال‌سازی (ENABLE) را انتخاب کنید. پس از اتمام فرآیند، Elevation API در لیست APIهای موجود در داشبورد ظاهر می‌شود.

قیمت‌گذاری و سیاست‌ها

قیمت‌گذاری

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

سیاست‌ها

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

درخواست‌های ارتفاع

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

پاسخ‌های ارتفاعی

برای هر درخواست معتبر، سرویس Elevation مجموعه‌ای از اشیاء ElevationResult را به همراه یک شیء ElevationStatus به callback تعریف شده برمی‌گرداند.

وضعیت‌های ارتفاع

هر درخواست ارتفاع، یک کد ElevationStatus را در تابع فراخوانی خود برمی‌گرداند. این کد status شامل یکی از مقادیر زیر خواهد بود:

• OK نشان می‌دهد که درخواست سرویس موفقیت‌آمیز بوده است
• INVALID_REQUEST نشان می‌دهد که درخواست سرویس ناقص بوده است.
• OVER_QUERY_LIMIT نشان می‌دهد که درخواست‌کننده از سهمیه تعیین‌شده تجاوز کرده است.
• REQUEST_DENIED نشان می‌دهد که سرویس درخواست را تکمیل نکرده است، احتمالاً به دلیل یک پارامتر نامعتبر.
• UNKNOWN_ERROR که خطای ناشناخته‌ای را نشان می‌دهد

شما باید با بررسی این کد وضعیت برای OK ، بررسی کنید که آیا فراخوانی شما با موفقیت انجام شده است یا خیر.

نتایج ارتفاع

پس از موفقیت، آرگومان results تابع callback شما شامل مجموعه‌ای از اشیاء ElevationResult خواهد بود. این اشیاء شامل عناصر زیر هستند:

• یک عنصر location (حاوی اشیاء LatLng ) از موقعیتی که داده‌های ارتفاع برای آن محاسبه می‌شود. توجه داشته باشید که برای درخواست‌های مسیر، مجموعه عناصر location شامل نقاط نمونه‌برداری شده در امتداد مسیر خواهد بود.
• یک عنصر elevation که ارتفاع محل را بر حسب متر نشان می‌دهد.
• یک مقدار resolution ، که نشان دهنده حداکثر فاصله بین نقاط داده‌ای است که ارتفاع از آنها درون‌یابی شده است، بر حسب متر. اگر وضوح مشخص نباشد، این ویژگی وجود نخواهد داشت. توجه داشته باشید که داده‌های ارتفاعی وقتی چندین نقطه عبور داده می‌شوند، جزئی‌تر (مقادیر resolution بزرگتر) می‌شوند. برای به دست آوردن دقیق‌ترین مقدار ارتفاع برای یک نقطه، باید آن را به طور مستقل جستجو کرد.

نمونه‌هایی از ارتفاع

کد زیر با استفاده از شیء LocationElevationRequest ، کلیک روی نقشه را به درخواست ارتفاع تبدیل می‌کند:

تایپ اسکریپت

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 را مطالعه کنید.

جاوا اسکریپت

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 ساخته می‌شود:

تایپ اسکریپت

// 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 را مطالعه کنید.

جاوا اسکریپت

// 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 کامپایل می‌شود.

مشاهده مثال