ऊंचाई के अनुरोध और जवाब

एलिवेशन के अनुरोध

Elevation API के अनुरोध, यूआरएल स्ट्रिंग के तौर पर बनाए जाते हैं. यह एपीआई, धरती पर मौजूद जगहों की ऊंचाई का डेटा दिखाता है. जगह की जानकारी का डेटा, इन दो में से किसी एक तरीके से दिया जा सकता है:

  • एक या उससे ज़्यादा locations के सेट के तौर पर.
  • path के साथ जुड़े हुए पॉइंट की सीरीज़ के तौर पर.

इनमें से कोई भी तरीका, जगहों या पाथ वर्टिस की पहचान करने के लिए, अक्षांश/देशांतर निर्देशांकों का इस्तेमाल करता है. इस दस्तावेज़ में, Elevation API के यूआरएल के लिए ज़रूरी फ़ॉर्मैट और उपलब्ध पैरामीटर के बारे में बताया गया है.

Elevation API, सिंगल पॉइंट क्वेरी के लिए डेटा दिखाता है. यह डेटा काफ़ी सटीक होता है. एक से ज़्यादा जगहों के लिए की गई बैच क्वेरी से, कम सटीक डेटा मिल सकता है. खास तौर पर, अगर जगहें एक-दूसरे से दूर हों, तो डेटा को स्मूद करने की वजह से ऐसा हो सकता है.

Elevation API का अनुरोध इस तरह का होता है:

https://maps.googleapis.com/maps/api/elevation/outputFormat?parameters

जहां outputFormat इनमें से कोई भी वैल्यू हो सकती है:

  • json (सुझाया गया), JavaScript ऑब्जेक्ट Notation (JSON) में आउटपुट दिखाता है; या
  • xml, इससे पता चलता है कि आउटपुट एक्सएमएल में है और <ElevationResponse> नोड में रैप किया गया है.

ध्यान दें: यूआरएल को मान्य बनाने के लिए, उन्हें सही तरीके से एन्कोड किया जाना चाहिए. साथ ही, सभी वेब सेवाओं के लिए, यूआरएल में ज़्यादा से ज़्यादा 16,384 वर्ण हो सकते हैं. अपने यूआरएल बनाते समय इस सीमा का ध्यान रखें. ध्यान दें कि अलग-अलग ब्राउज़र, प्रॉक्सी, और सर्वर के लिए, यूआरएल में वर्णों की सीमाएं भी अलग-अलग हो सकती हैं.

एपीआई पासकोड का इस्तेमाल करने वाले अनुरोधों के लिए, एचटीटीपीएस ज़रूरी है.

अनुरोध के पैरामीटर

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

सभी यूआरएल में स्टैंडर्ड के तौर पर, पैरामीटर को एंपरसैंड (&amp;) वर्ण का इस्तेमाल करके अलग किया जाता है. पैरामीटर और उनकी संभावित वैल्यू की सूची यहां दी गई है.

सभी अनुरोध

  • key -- (ज़रूरी है) आपके ऐप्लिकेशन का एपीआई पासकोड. यह कुंजी, कोटा मैनेजमेंट के लिए आपके ऐप्लिकेशन की पहचान करती है. कुंजी पाने का तरीका जानें.

पोज़िशन के हिसाब से अनुरोध

  • locations (ज़रूरी है) से, धरती पर मौजूद उन जगहों के बारे में पता चलता है जिनकी ऊंचाई का डेटा दिखाना है. यह पैरामीटर, कॉमा लगाकर अलग किए गए {latitude,longitude} जोड़ी के तौर पर एक जगह की जानकारी लेता है.उदाहरण के लिए, "40.714728,-73.998672". इसके अलावा, यह पैरामीटर, ऐरे या एन्कोड की गई पॉलीलाइन के तौर पर पास की गई कई अक्षांश/देशांतर जोड़ियों को भी लेता है. इस पैरामीटर के लिए, 512 पॉइंट की सीमा है. ज़्यादा जानकारी के लिए, नीचे दिया गया जगहें तय करना लेख पढ़ें.

सैंपल किए गए पाथ के अनुरोध

  • path (ज़रूरी है) पृथ्वी पर एक पाथ तय करता है, जिसके लिए ऊंचाई का डेटा दिखाया जाता है. यह पैरामीटर, दो या उससे ज़्यादा {अक्षांश, देशांतर} के क्रम में लगाए गए जोड़ों का सेट तय करता है. यह सेट, पृथ्वी की सतह पर मौजूद किसी पाथ के बारे में बताता है. इस पैरामीटर का इस्तेमाल, यहां बताए गए samples पैरामीटर के साथ किया जाना चाहिए. इस पैरामीटर के लिए, 512 पॉइंट की सीमा है. ज़्यादा जानकारी के लिए, नीचे दिया गया पाथ तय करना सेक्शन देखें.
  • samples (ज़रूरी है) से, किसी पाथ पर मौजूद उन सैंपल पॉइंट की संख्या तय होती है जिनके लिए ऊंचाई का डेटा दिखाना है. samples पैरामीटर, दिए गए path को पाथ के साथ बराबर दूरी पर मौजूद पॉइंट के क्रम में बांटता है.

जगहों की जानकारी दें

जगह के हिसाब से किए जाने वाले अनुरोधों को locations पैरामीटर का इस्तेमाल करके दिखाया जाता है. इससे अक्षांश/देशांतर वैल्यू के तौर पर पास की गई खास जगहों के लिए, ऊंचाई के अनुरोधों का पता चलता है.

locations पैरामीटर में ये आर्ग्युमेंट शामिल हो सकते हैं:

  • एक कोऑर्डिनेट: locations=40.714728,-73.998672
  • पाइप ('|') वर्ण का इस्तेमाल करके अलग किए गए निर्देशांकों का कलेक्शन: locations=40.714728,-73.998672|-34.397,150.644
  • एन्कोड की गई पॉलीलाइन एल्गोरिदम का इस्तेमाल करके एन्कोड किए गए निर्देशांकों का सेट: locations=enc:gfo}EtohhU

अक्षांश और देशांतर निर्देशांक स्ट्रिंग को कॉमा लगाकर अलग किए गए टेक्स्ट स्ट्रिंग में अंकों का इस्तेमाल करके तय किया जाता है. उदाहरण के लिए, "40.714728,-73.998672" locations की मान्य वैल्यू है. अक्षांश और देशांतर की वैल्यू, धरती पर मौजूद किसी मान्य जगह की होनी चाहिए. अक्षांश की वैल्यू, -90 और 90 के बीच की कोई भी वैल्यू हो सकती है. वहीं, देशांतर की वैल्यू, -180 और 180 के बीच की कोई भी वैल्यू हो सकती है. अगर अक्षांश या देशांतर की कोई अमान्य वैल्यू दी जाती है, तो आपके अनुरोध को गलत अनुरोध के तौर पर अस्वीकार कर दिया जाएगा.

किसी अरे या एन्कोड की गई पॉलीलाइन में, ज़्यादा से ज़्यादा 512 निर्देशांक पास किए जा सकते हैं. हालांकि, इसके लिए ज़रूरी है कि यूआरएल मान्य हो. ध्यान दें कि एक से ज़्यादा निर्देशांक पास करने पर, मिले डेटा की सटीक जानकारी का रिज़ॉल्यूशन, एक निर्देशांक के लिए डेटा का अनुरोध करने पर मिले डेटा की तुलना में कम हो सकता है. 'locations' या 'path' पैरामीटर में 512 से ज़्यादा पॉइंट या निर्देशांक होने पर, INVALID_REQUEST रिस्पॉन्स मिलता है.

पाथ तय करना

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

path पैरामीटर में, इनमें से कोई भी आर्ग्युमेंट हो सकता है:

  • कॉमा लगाकर अलग की गई दो या इससे ज़्यादा कोऑर्डिनेट टेक्स्ट स्ट्रिंग का कलेक्शन, जिसे पाइप ('|') वर्ण का इस्तेमाल करके अलग किया गया है: path=40.714728,-73.998672|-34.397,150.644
  • एन्कोड की गई पॉलीलाइन एल्गोरिदम का इस्तेमाल करके एन्कोड किए गए कोऑर्डिनेट: path=enc:gfo}EtohhUxD@bAxJmGF

अक्षांश और देशांतर के निर्देशांक की स्ट्रिंग को, कॉमा लगाकर अलग की गई टेक्स्ट स्ट्रिंग में अंकों का इस्तेमाल करके तय किया जाता है. उदाहरण के लिए, "40.714728,-73.998672|-34.397, 150.644" path की मान्य वैल्यू है. अक्षांश और देशांतर की वैल्यू, धरती पर मौजूद किसी मान्य जगह की होनी चाहिए. अक्षांश की वैल्यू -90 और 90 के बीच की कोई भी वैल्यू हो सकती है. वहीं, देशांतर की वैल्यू -180 और 180 के बीच की कोई भी वैल्यू हो सकती है. अगर अक्षांश या देशांतर की वैल्यू अमान्य है, तो आपके अनुरोध को गलत अनुरोध के तौर पर अस्वीकार कर दिया जाएगा.

किसी अरे या एन्कोड की गई पॉलीलाइन में, ज़्यादा से ज़्यादा 512 निर्देशांक पास किए जा सकते हैं. हालांकि, इसके लिए ज़रूरी है कि यूआरएल मान्य हो. ध्यान दें कि एक से ज़्यादा निर्देशांक पास करने पर, मिले डेटा की सटीक जानकारी का रिज़ॉल्यूशन, एक निर्देशांक के लिए डेटा का अनुरोध करने पर मिले डेटा की तुलना में कम हो सकता है. 'locations' या 'path' पैरामीटर में 512 पॉइंट या निर्देशांक से ज़्यादा होने पर, INVALID_REQUEST रिस्पॉन्स मिलता है.

ऊंचाई से जुड़े जवाब

  • कॉमा लगाकर अलग की गई दो या इससे ज़्यादा कोऑर्डिनेट टेक्स्ट स्ट्रिंग का कलेक्शन, जिसे पाइप ('|') वर्ण का इस्तेमाल करके अलग किया गया है: path=40.714728,-73.998672|-34.397,150.644
  • एन्कोड की गई पॉलीलाइन एल्गोरिदम का इस्तेमाल करके एन्कोड किए गए कोऑर्डिनेट: path=enc:gfo}EtohhUxD@bAxJmGF

अक्षांश और देशांतर के निर्देशांक की स्ट्रिंग को, कॉमा लगाकर अलग की गई टेक्स्ट स्ट्रिंग में अंकों का इस्तेमाल करके तय किया जाता है. उदाहरण के लिए, "40.714728,-73.998672|-34.397, 150.644" path की मान्य वैल्यू है. अक्षांश और देशांतर की वैल्यू, धरती पर मौजूद किसी मान्य जगह की होनी चाहिए. अक्षांश की वैल्यू, -90 और 90 के बीच की कोई भी वैल्यू हो सकती है. वहीं, देशांतर की वैल्यू, -180 और -180 के बीच की कोई भी वैल्यू हो सकती है. अगर अक्षांश या देशांतर की वैल्यू अमान्य है, तो आपके अनुरोध को गलत अनुरोध के तौर पर अस्वीकार कर दिया जाएगा.

किसी अरे या एन्कोड की गई पॉलीलाइन में, ज़्यादा से ज़्यादा 512 निर्देशांक पास किए जा सकते हैं. हालांकि, इसके लिए ज़रूरी है कि यूआरएल मान्य हो. ध्यान दें कि एक से ज़्यादा निर्देशांक पास करने पर, मिले डेटा की सटीक जानकारी का रिज़ॉल्यूशन, एक निर्देशांक के लिए डेटा का अनुरोध करने पर मिले डेटा की तुलना में कम हो सकता है. 'locations' या 'path' पैरामीटर में 512 पॉइंट या निर्देशांक से ज़्यादा होने पर, INVALID_REQUEST रिस्पॉन्स मिलता है.

ऊंचाई से जुड़े जवाब

हर मान्य अनुरोध के लिए, Elevation सेवा, अनुरोध के यूआरएल में बताए गए फ़ॉर्मैट में Elevation रिस्पॉन्स दिखाती है.

ElevationResponse

फ़ील्ड ज़रूरी है टाइप ब्यौरा
ज़रूरी है Array<ElevationResult> ज़्यादा जानकारी के लिए, ElevationResult देखें.
ज़रूरी है ElevationStatus ज़्यादा जानकारी के लिए, ElevationStatus देखें.
ज़रूरी नहीं स्ट्रिंग

जब सेवा OK के अलावा कोई दूसरा स्टेटस कोड दिखाती है, तो रिस्पॉन्स ऑब्जेक्ट में एक और error_message फ़ील्ड हो सकता है. इस फ़ील्ड में, दिए गए स्टेटस कोड की वजहों के बारे में ज़्यादा जानकारी होती है. यह फ़ील्ड हमेशा नहीं दिखता. साथ ही, इसके कॉन्टेंट में बदलाव हो सकता है.

ElevationStatus

सेवा से मिले स्टेटस कोड.

  • OK, जिससे पता चलता है कि एपीआई अनुरोध पूरा हो गया है.
  • DATA_NOT_AVAILABLE, जिससे पता चलता है कि इनपुट की गई जगहों के लिए कोई डेटा उपलब्ध नहीं है.
  • INVALID_REQUEST, जिससे पता चलता है कि एपीआई अनुरोध गलत तरीके से बनाया गया था.
  • OVER_DAILY_LIMIT, जो इनमें से किसी एक के बारे में बताता है:
    • एपीआई पासकोड मौजूद नहीं है या अमान्य है.
    • आपके खाते के लिए बिलिंग की सुविधा चालू नहीं की गई है.
    • आपने इस्तेमाल की जो सीमा तय की थी वह पूरी हो गई है.
    • पेमेंट का दिया गया तरीका अब मान्य नहीं है. उदाहरण के लिए, क्रेडिट कार्ड की समयसीमा खत्म हो गई है.
  • OVER_QUERY_LIMIT, जिससे पता चलता है कि अनुरोध करने वाले व्यक्ति ने कोटा पार कर लिया है.
  • REQUEST_DENIED, जिससे पता चलता है कि एपीआई ने अनुरोध पूरा नहीं किया.
  • UNKNOWN_ERROR, जिससे किसी अज्ञात गड़बड़ी का पता चलता है.

जब स्टेटस कोड OK के अलावा कुछ और होता है, तो Elevation रिस्पॉन्स ऑब्जेक्ट में एक और error_message फ़ील्ड हो सकता है. इस फ़ील्ड में, दिए गए स्टेटस कोड की वजहों के बारे में ज़्यादा जानकारी होती है.

रिस्पॉन्स में एक results कलेक्शन होता है, जिसमें ये एलिमेंट होते हैं:

ElevationResult

फ़ील्ड ज़रूरी है टाइप ब्यौरा
ज़रूरी है संख्या

मीटर में जगह की ऊंचाई.
ज़रूरी है LatLngLiteral

उस जगह की जानकारी का एलिमेंट जिसके लिए ऊंचाई का डेटा कंप्यूट किया जा रहा है. ध्यान दें कि पाथ के अनुरोधों के लिए, जगह के एलिमेंट के सेट में पाथ के सैंपल पॉइंट शामिल होंगे.

ज़्यादा जानकारी के लिए, LatLngLiteral देखें.

ज़रूरी नहीं संख्या

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

LatLngLiteral

दशमलव डिग्री में अक्षांश और देशांतर के साथ किसी खास जगह की जानकारी देने वाला ऑब्जेक्ट.

फ़ील्ड ज़रूरी है टाइप ब्यौरा
ज़रूरी है संख्या

दशमलव डिग्री में अक्षांश
ज़रूरी है संख्या

दशमलव डिग्री में देशांतर

पोज़िशनल एलिवेशन के उदाहरण

नीचे दिए गए उदाहरण में, "माइल हाई सिटी" के नाम से मशहूर, कोलोराडो के डेनवर शहर की ऊंचाई का अनुरोध किया गया है:

URL

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034
    &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034&key=YOUR_API_KEY'

JSON

        
{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
    ],
  "status": "OK",
}

XML

        
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
</ElevationResponse>

यहां दिए गए उदाहरण में, डेनवर, कोलोराडो और डेथ वैली, कैलिफ़ोर्निया के लिए कई जवाब दिखाए गए हैं.

इस अनुरोध में, JSON output फ़्लैग का इस्तेमाल दिखाया गया है:

URL

https://maps.googleapis.com/maps/api/elevation/json
    ?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667
    &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?locations=39.7391536%2C-104.9847034%7C36.455556%2C-116.866667&key=YOUR_API_KEY'

इस अनुरोध में, एक्सएमएल output फ़्लैग का इस्तेमाल दिखाया गया है:

https://maps.googleapis.com/maps/api/elevation/xml?locations=39.7391536,-104.9847034|36.455556,-116.866667&key=YOUR_API_KEY

JSON और एक्सएमएल रिस्पॉन्स के सैंपल देखने के लिए, यहां दिए गए टैब चुनें.

JSON

      
{
  "results":
    [
      {
        "elevation": 1608.637939453125,
        "location": { "lat": 39.7391536, "lng": -104.9847034 },
        "resolution": 4.771975994110107,
      },
      {
        "elevation": -52.79492568969727,
        "location": { "lat": 36.455556, "lng": -116.866667 },
        "resolution": 19.08790397644043,
      },
    ],
  "status": "OK",
}

XML

      
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>39.7391536</lat>
   <lng>-104.9847034</lng>
  </location>
  <elevation>1608.6379395</elevation>
  <resolution>4.7719760</resolution>
 </result>
 <result>
  <location>
   <lat>36.4555560</lat>
   <lng>-116.8666670</lng>
  </location>
  <elevation>-52.7949257</elevation>
  <resolution>19.0879040</resolution>
 </result>
</ElevationResponse>

नीचे दिए गए उदाहरण में, अमेरिका के सबसे ऊंचे और सबसे निचले पॉइंट, कैलिफ़ोर्निया के माउंट व्हिटनी से कैलिफ़ोर्निया के बैडवॉटर तक की सीधी लाइन path के लिए, ऊंचाई का डेटा मांगा गया है. हम तीन samples मांगते हैं, ताकि उनमें दो एंडपॉइंट और आधा पॉइंट शामिल हो सके.

URL

https://maps.googleapis.com/maps/api/elevation/json
  ?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171
  &samples=3
  &key=YOUR_API_KEY

cURL

curl -L -X GET 'https://maps.googleapis.com/maps/api/elevation/json?path=36.578581%2C-118.291994%7C36.23998%2C-116.83171&samples=3&key=YOUR_API_KEY'

JSON

      
{
  "results":
    [
      {
        "elevation": 4411.94189453125,
        "location": { "lat": 36.578581, "lng": -118.291994 },
        "resolution": 19.08790397644043,
      },
      {
        "elevation": 1372.8359375,
        "location": { "lat": 36.41150289067028, "lng": -117.5602607523847 },
        "resolution": 9.543951988220215,
      },
      {
        "elevation": -84.51690673828125,
        "location": { "lat": 36.23998, "lng": -116.83171 },
        "resolution": 9.543951988220215,
      },
    ],
  "status": "OK",
}

XML

      
<ElevationResponse>
 <status>OK</status>
 <result>
  <location>
   <lat>36.5785810</lat>
   <lng>-118.2919940</lng>
  </location>
  <elevation>4411.9418945</elevation>
  <resolution>19.0879040</resolution>
 </result>
 <result>
  <location>
   <lat>36.4115029</lat>
   <lng>-117.5602608</lng>
  </location>
  <elevation>1372.8359375</elevation>
  <resolution>9.5439520</resolution>
 </result>
 <result>
  <location>
   <lat>36.2399800</lat>
   <lng>-116.8317100</lng>
  </location>
  <elevation>-84.5169067</elevation>
  <resolution>9.5439520</resolution>
 </result>
</ElevationResponse>