سرویس ارتفاع

نمای کلی

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

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

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

شروع کردن

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

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

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

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

قیمت گذاری

از 16 ژوئیه 2018، یک طرح جدید قیمت‌گذاری پرداختی برای Maps، Routes و Places اجرا شد. برای کسب اطلاعات بیشتر در مورد قیمت‌گذاری و محدودیت‌های استفاده جدید برای استفاده از سرویس JavaScript Elevation، به Usage and Billing for Elevation API مراجعه کنید.

سیاست ها

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

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

دسترسی به سرویس Elevation ناهمزمان است، زیرا Google Maps API باید با یک سرور خارجی تماس بگیرد. به همین دلیل، باید پس از تکمیل درخواست، یک متد برگشتی را ارسال کنید تا اجرا شود. این روش برگشتی باید نتیجه(های) را پردازش کند. توجه داشته باشید که سرویس Elevation یک کد وضعیت ( ElevationStatus ) و آرایه ای از اشیاء ElevationResult جداگانه را برمی گرداند.

ElevationService دو نوع درخواست را انجام می دهد:

  • درخواست مکان‌های مجزا و مجزا با استفاده از متد getElevationForLocations() ، که فهرستی از یک یا چند مکان را با استفاده از یک شی LocationElevationRequest ارسال می‌کند.
  • درخواست ارتفاع در یک سری از نقاط متصل در طول یک مسیر با استفاده از متد getElevationAlongPath() که مجموعه مرتبی از رئوس مسیر را در یک شی PathElevationRequest ارسال می کند. هنگام درخواست ارتفاع در امتداد مسیرها، باید پارامتری را نیز ارسال کنید که نشان می دهد چند نمونه از آن مسیر را می خواهید بگیرید.

هر یک از این متدها همچنین باید یک متد برگشتی برای مدیریت اشیاء ElevationResult و ElevationStatus برگشتی ارسال کنند.

درخواست ارتفاع مکان

یک شیء LocationElevationRequest حاوی فیلد زیر است:

{
  locations[]: LatLng
}

locations (لازم) مکان(های) روی زمین را که از آن داده های ارتفاعی برگردانده می شود، تعریف می کند. این پارامتر آرایه ای از LatLng s را می گیرد.

تا زمانی که از سهمیه خدمات تجاوز نکنید، می‌توانید هر تعداد مختصات چندگانه را در یک آرایه ارسال کنید. توجه داشته باشید که هنگام ارسال چند مختصات، دقت هر داده بازگشتی ممکن است وضوح کمتری نسبت به درخواست داده برای یک مختصات داشته باشد.

نمونه درخواست ارتفاع مسیر

یک شیء PathElevationRequest حاوی فیلدهای زیر است:

{
  path[]: LatLng,
  samples: Number
}

این فیلدها در زیر توضیح داده شده است:

  • path (لازم) مسیری را روی زمین تعریف می کند که برای آن داده های ارتفاعی را برگرداند. پارامتر path مجموعه ای از دو یا چند جفت مرتب شده {latitude,longitude} را با استفاده از آرایه ای از دو یا چند شی LatLng تعریف می کند.
  • samples (الزامی) تعداد نقاط نمونه را در طول مسیری که داده های ارتفاعی برای آنها برگردانده می شود، مشخص می کند. پارامتر samples path داده شده را به مجموعه منظمی از نقاط مساوی در طول مسیر تقسیم می کند.

همانند درخواست های موقعیتی، پارامتر path مجموعه ای از مقادیر طول و عرض جغرافیایی را مشخص می کند. با این حال، بر خلاف یک درخواست موقعیتی، path مجموعه ای مرتب از رئوس را مشخص می کند. به‌جای بازگشت داده‌های ارتفاع در راس‌ها، درخواست‌های مسیر در طول مسیر نمونه‌برداری می‌شوند، جایی که هر نمونه از یکدیگر فاصله دارد (شامل نقاط پایانی).

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

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

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

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

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

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

نتایج ارتفاع

پس از موفقیت، آرگومان results تابع callback شما حاوی مجموعه ای از اشیاء 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

جاوا اسکریپت

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
مشاهده نمونه

Sample را امتحان کنید

مثال زیر یک چند خط با مجموعه‌ای از مختصات می‌سازد و داده‌های ارتفاع را در آن مسیر با استفاده از Google Visualization API نمایش می‌دهد. (شما باید این API را با استفاده از Google Common Loader بارگیری کنید.) یک درخواست elevation با استفاده از 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

جاوا اسکریپت

// 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
مشاهده نمونه

Sample را امتحان کنید