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

ऊंचाई से जुड़े अनुरोध

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

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

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

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

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

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

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

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

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

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

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

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

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

सभी अनुरोध

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

जगह की जानकारी के अनुरोध

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

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

• path (ज़रूरी है) पृथ्वी पर मौजूद किसी ऐसे पाथ को तय करता है जिसके लिए ऊंचाई का डेटा दिखाना है. यह पैरामीटर, {latitude,longitude} के दो या उससे ज़्यादा क्रम वाले जोड़े का सेट तय करता है. यह सेट, पृथ्वी की सतह पर किसी पाथ को तय करता है. इस पैरामीटर का इस्तेमाल, नीचे दिए गए 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 रिस्पॉन्स मिलता है.

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

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

ElevationResponse

ElevationStatus

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

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

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

जवाब में, results ऐरे होता है. इसमें ये एलिमेंट होते हैं:

ElevationResult

LatLngLiteral

यह एक ऐसा ऑब्जेक्ट है जो किसी जगह के बारे में बताता है. इसमें अक्षांश और देशांतर की जानकारी, डेसिमल डिग्री में होती है.

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

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

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

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

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

        
<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 फ़्लैग का इस्तेमाल करने का तरीका दिखाया गया है:

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

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 और XML के जवाबों के उदाहरण देखने के लिए, यहां दिए गए टैब चुनें.

      
{
  "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",
}
      
      

      
<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 के लिए अनुरोध करते हैं, ताकि इसमें दो एंडपॉइंट और बीच का पॉइंट शामिल हो.

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 -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'
    

      
{
  "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",
}
      
      

      
<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>