Elevation Service

ध्यान दें: सर्वर-साइड लाइब्रेरी

इस पेज पर, Maps JavaScript API के साथ उपलब्ध क्लाइंट-साइड सेवा के बारे में बताया गया है. अगर आपको अपने सर्वर पर Google Maps की वेब सेवाओं का इस्तेमाल करना है, तो Google Maps की सेवाओं के लिए Node.js क्लाइंट, Java क्लाइंट, Python क्लाइंट, और Google Maps की सेवाओं के लिए Go क्लाइंट देखें.

खास जानकारी

Maps JavaScript API के एपीआई का संदर्भ भी देखें: ऊंचाई

एलिवेशन सर्विस, धरती की सतह पर मौजूद जगहों की ऊंचाई का डेटा उपलब्ध कराती है. इसमें महासागरीय तल की गहराई वाली जगहों का डेटा भी शामिल है. हालांकि, गहराई वाली जगहों की वैल्यू नेगेटिव होती है. अगर Google के पास आपकी बताई गई जगह की सटीक ऊंचाई की जानकारी नहीं है, तो सेवा, आस-पास की चार जगहों की जानकारी का इस्तेमाल करके, औसत वैल्यू दिखाएगी.

ElevationService ऑब्जेक्ट, आपको धरती पर किसी जगह की ऊंचाई का डेटा पाने की क्वेरी के लिए, एक आसान इंटरफ़ेस उपलब्ध कराता है. इसके अलावा, रास्तों के लिए सैंपल किए गए एलिवेशन डेटा का अनुरोध किया जा सकता है. इससे आपको रास्तों पर, बराबर दूरी पर होने वाले एलिवेशन में बदलावों का हिसाब लगाने में मदद मिलती है. ElevationService ऑब्जेक्ट, Google Maps API की एलिवेशन सर्विस के साथ कम्यूनिकेट करता है. यह सर्विस, एलिवेशन के अनुरोधों को स्वीकार करती है और एलिवेशन डेटा दिखाती है.

एलिवेशन सर्विस की मदद से, हाइकिंग और साइकल चलाने वाले ऐप्लिकेशन, मोबाइल की पोज़िशनिंग वाले ऐप्लिकेशन या कम रिज़ॉल्यूशन वाले सर्वे ऐप्लिकेशन बनाए जा सकते हैं.

शुरू करना

Maps JavaScript API में ऊंचाई बताने वाली सेवा का इस्तेमाल करने से पहले, पक्का करें कि Google Cloud Console में Elevation API चालू हो. यह उसी प्रोजेक्ट में चालू होना चाहिए जिसे आपने Maps JavaScript API के लिए सेट अप किया है.

चालू किए गए एपीआई की सूची देखने के लिए:

1. Google Cloud console पर जाएं.
2. कोई प्रोजेक्ट चुनें बटन पर क्लिक करें. इसके बाद, वही प्रोजेक्ट चुनें जिसे आपने Maps JavaScript API के लिए सेट अप किया है. इसके बाद, खोलें पर क्लिक करें.
3. डैशबोर्ड पर मौजूद एपीआई की सूची में, Elevation API ढूंढें.
4. अगर आपको सूची में एपीआई दिखता है, तो आपको कोई कार्रवाई करने की ज़रूरत नहीं है. अगर एपीआई सूची में नहीं है, तो उसे चालू करें:
   1. लाइब्रेरी टैब दिखाने के लिए, पेज पर सबसे ऊपर मौजूद एपीआई चालू करें को चुनें. इसके अलावा, बाईं ओर मौजूद मेन्यू में जाकर, लाइब्रेरी को चुनें.
   2. Elevation API खोजें. इसके बाद, नतीजों की सूची से इसे चुनें.
   3. चालू करें को चुनें. प्रोसेस पूरी होने के बाद, Elevation API, डैशबोर्ड पर एपीआई की सूची में दिखता है.

कीमत और नीतियां

कीमत

JavaScript 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 पैरामीटर, दो या इससे ज़्यादा LatLng ऑब्जेक्ट के कलेक्शन का इस्तेमाल करके, क्रम से लगाए गए दो या इससे ज़्यादा {latitude,longitude} पेयर का सेट तय करता है.
• 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 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 का इस्तेमाल करके, उस पाथ के साथ ऊंचाई का डेटा दिखाया गया है. (आपको 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

ध्यान दें: JavaScript को TypeScript स्निपेट से कंपाइल किया जाता है.

उदाहरण देखें