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

ऊंचाई के अनुरोध

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

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

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

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

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

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

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

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

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

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

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

Elevation 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 निर्देशांक डाले जा सकते हैं. ध्यान दें कि एक से ज़्यादा निर्देशांक पास करने पर, मिलने वाले डेटा की सटीक जानकारी, एक निर्देशांक के लिए डेटा का अनुरोध करने के मुकाबले कम हो सकती है. 'जगहें' या 'पाथ' पैरामीटर में 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 निर्देशांक डाले जा सकते हैं. ध्यान दें कि एक से ज़्यादा कोऑर्डिनेट पास करने पर, मिलने वाले डेटा की सटीक जानकारी, एक कोऑर्डिनेट के लिए डेटा का अनुरोध करने के मुकाबले कम हो सकती है. 'जगहें' या 'पाथ' पैरामीटर में 512 पॉइंट या निर्देशांक से ज़्यादा होने पर, INVALID_REQUEST रिस्पॉन्स मिलता है.

ऊंचाई के जवाब

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

ElevationResponse

Field	Required	Type	Description
results	required	Array<ElevationResult>	See ElevationResult for more information.
status	required	ElevationStatus	See ElevationStatus for more information.
error_message	optional	string	When the service returns a status code other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about thereasons behind the given status code. This field is not always returned, and its content is subject to change.

ElevationStatus

Status codes returned by service.

• OK indicating the API request was successful.
• DATA_NOT_AVAILABLE indicating that there's no available data for the input locations.
• INVALID_REQUEST indicating the API request was malformed.
• OVER_DAILY_LIMIT indicating any of the following:
  • The API key is missing or invalid.
  • Billing has not been enabled on your account.
  • A self-imposed usage cap has been exceeded.
  • The provided method of payment is no longer valid (for example, a credit card has expired).
• OVER_QUERY_LIMIT indicating the requestor has exceeded quota.
• REQUEST_DENIED indicating the API did not complete the request.
• UNKNOWN_ERROR indicating an unknown error.

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

ध्यान दें: इस बात की कोई गारंटी नहीं है कि यह फ़ील्ड हमेशा मौजूद रहेगा. साथ ही, इसके कॉन्टेंट में बदलाव हो सकता है.

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

ElevationResult

Field	Required	Type	Description
elevation	required	number	The elevation of the location in meters.
location	required	LatLngLiteral	A location element of the position for which elevation data is being computed. Note that for path requests, the set of location elements will contain the sampled points along the path. See LatLngLiteral for more information.
resolution	optional	number	The value indicating the maximum distance between data points from which the elevation was interpolated, in meters. This property will be missing if the resolution is not known. Note that elevation data becomes more coarse (larger resolution values) when multiple points are passed. To obtain the most accurate elevation value for a point, it should be queried independently.

location ऑब्जेक्ट में ये एलिमेंट होते हैं:

LatLngLiteral

An object describing a specific location with Latitude and Longitude in decimal degrees.

Field	Required	Type	Description
lat	required	number	Latitude in decimal degrees
lng	required	number	Longitude in decimal degrees

पोज़िशन की ऊंचाई के उदाहरण

नीचे दिए गए उदाहरण में, कोलोराडो के डेनवर शहर की ऊंचाई का अनुरोध, JSON फ़ॉर्मैट में किया गया है. डेनवर को "माइल हाई सिटी" कहा जाता है:

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>