समय क्षेत्र के लिए अनुरोध और उनके जवाब

समय क्षेत्र

Time Zone API के अनुरोध, यूआरएल स्ट्रिंग के तौर पर बनाए जाते हैं. यह एपीआई, पृथ्वी पर मौजूद किसी जगह के लिए टाइम ज़ोन का डेटा दिखाता है. इस जगह की जानकारी, अक्षांश-देशांतर के जोड़े से मिलती है. ध्यान दें कि पानी में मौजूद जगहों के लिए, टाइम ज़ोन का डेटा उपलब्ध नहीं हो सकता. जैसे, महासागर या समुद्र.

टाइम ज़ोन का अनुरोध इस फ़ॉर्मैट में होता है:

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

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

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

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

ज़रूरी पैरामीटर

  • जगह

    कॉमा से अलग किया गया अक्षांश, देशांतर टपल, location=39.6034810,-119.6822510. यह उस जगह को दिखाता है जिसके लिए टाइम ज़ोन का डेटा देखना है.

  • timestamp

    यह वह समय है जो 1 जनवरी, 1970 को यूटीसी के मुताबिक, आधी रात से लेकर अब तक के सेकंड में दिखाया जाता है. Time Zone API, timestamp का इस्तेमाल करके यह तय करता है कि डेलाइट सेविंग टाइम लागू किया जाना चाहिए या नहीं. यह फ़ैसला, location के टाइम ज़ोन के आधार पर लिया जाता है.

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

ज़रूरी नहीं पैरामीटर

  • भाषा

    वह भाषा जिसमें नतीजे दिखाने हैं.

    • इस्तेमाल की जा सकने वाली भाषाओं की सूची देखें. Google, इस्तेमाल की जा सकने वाली भाषाओं को अक्सर अपडेट करता है. इसलिए, हो सकता है कि इस सूची में सभी भाषाएं शामिल न हों.
    • अगर language की जानकारी नहीं दी जाती है, तो एपीआई, पसंदीदा भाषा का इस्तेमाल करने की कोशिश करता है, जैसा कि Accept-Language हेडर में तय किया गया है.
    • एपीआई, मोहल्ले का ऐसा पता उपलब्ध कराने की पूरी कोशिश करता है जिसे उपयोगकर्ता और स्थानीय लोग, दोनों आसानी से पढ़ सकें. इसके लिए, एपीआई, मोहल्ले के पते को स्थानीय भाषा में दिखाता है. साथ ही, अगर ज़रूरी हो, तो इसे उपयोगकर्ता की पसंदीदा भाषा में लिप्यंतरित करके दिखाता है. बाकी सभी पते, पसंदीदा भाषा में दिखाए जाते हैं. पते के सभी कॉम्पोनेंट एक ही भाषा में दिखाए जाते हैं. यह भाषा, पहले कॉम्पोनेंट से चुनी जाती है.
    • अगर कोई नाम, पसंदीदा भाषा में उपलब्ध नहीं है, तो एपीआई, उससे मिलती-जुलती भाषा का इस्तेमाल करता है.
    • पसंदीदा भाषा का, एपीआई से मिलने वाले नतीजों के सेट और उनके क्रम पर थोड़ा असर पड़ता है. जियोकोडर, भाषा के हिसाब से शॉर्ट फ़ॉर्म को अलग-अलग तरीके से समझता है. जैसे, सड़कों के टाइप के लिए इस्तेमाल किए जाने वाले शॉर्ट फ़ॉर्म या ऐसे समानार्थी शब्द जो एक भाषा में मान्य हो सकते हैं, लेकिन दूसरी भाषा में नहीं. उदाहरण के लिए, utca और tér हंगेरियन में सड़क के समानार्थी शब्द हैं.

टाइम ज़ोन के उदाहरण

इस सेक्शन में, कुछ सैंपल क्वेरी शामिल हैं. इनसे एपीआई की सुविधाओं के बारे में पता चलता है.

नीचे दी गई क्वेरी, अमेरिका के नेवाडा के लिए टाइम ज़ोन का अनुरोध करती है. इसमें timestamp को 5 दिसंबर, 2024 पर सेट किया गया है.

URL

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 0,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "Pacific Standard Time",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>0.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>Pacific Standard Time</time_zone_name>
</TimeZoneResponse>

नीचे दी गई क्वेरी, अमेरिका के नेवाडा के लिए टाइम ज़ोन का अनुरोध करती है. इसमें जगह की जानकारी, ऊपर दिए गए अनुरोध के जैसी ही है. हालांकि, timestamp को 15 मार्च, 2024 पर सेट किया गया है. जवाब में अब डेलाइट सेविंग टाइम का ऑफ़सेट शामिल है.

URL

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 3600,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "Pacific Daylight Time",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>3600.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>Pacific Daylight Time</time_zone_name>
</TimeZoneResponse>

यह उदाहरण, ऊपर दिए गए दोनों उदाहरणों जैसा ही है. हालांकि, इसमें भाषा का पैरामीटर सेट किया गया है. जवाब अब स्पैनिश में दिखेगा.

URL

https://maps.googleapis.com/maps/api/timezone/json?language=es&location=39.6034810,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&language=es&key=YOUR_API_KEY'

JSON

{
  "dstOffset": 3600,
  "rawOffset": -28800,
  "status": "OK",
  "timeZoneId": "America/Los_Angeles",
  "timeZoneName": "hora de verano del Pacífico",
}

XML

<TimeZoneResponse>
 <status>OK</status>
 <raw_offset>-28800.0000000</raw_offset>
 <dst_offset>3600.0000000</dst_offset>
 <time_zone_id>America/Los_Angeles</time_zone_id>
 <time_zone_name>hora de verano del Pacífico</time_zone_name>
</TimeZoneResponse>

टाइम ज़ोन के जवाब

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

TimeZoneResponse

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

डेलाइट सेविंग टाइम के लिए ऑफ़सेट (सेकंड में). अगर तय किए गए timestamp के दौरान, टाइम ज़ोन डेलाइट सेविंग टाइम में नहीं है, तो इसकी वैल्यू शून्य होगी.

ज़रूरी नहीं स्ट्रिंग

दिए गए स्टेटस कोड की वजहों के बारे में ज़्यादा जानकारी. यह तब शामिल किया जाता है, जब स्टेटस Ok के अलावा कोई और हो.

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

दी गई जगह के लिए, यूटीसी से ऑफ़सेट (सेकंड में). इसमें डेलाइट सेविंग टाइम शामिल नहीं होता.

ज़रूरी नहीं स्ट्रिंग

यह एक स्ट्रिंग है, जिसमें टाइम ज़ोन का आईडी होता है. जैसे, "America/Los_Angeles" या "Australia/Sydney". ये आईडी, यूनिकोड कॉमन लोकेल डेटा रिपॉज़िटरी (सीएलडीआर) प्रोजेक्ट से तय किए जाते हैं. फ़िलहाल, ये timezone.xml फ़ाइल में उपलब्ध हैं. जब किसी टाइमज़ोन के कई आईडी होते हैं, तो कैननिकल आईडी दिखाया जाता है. एक्सएमएल में दिए गए जवाबों में, यह हर टाइमज़ोन का पहला एलियास होता है. उदाहरण के लिए, "Asia/Calcutta" दिखाया जाता है है, "Asia/Kolkata" नहीं.

ज़रूरी नहीं स्ट्रिंग

टाइम ज़ोन का पूरा नाम. अगर भाषा का पैरामीटर सेट किया जाता है, तो इस फ़ील्ड को स्थानीय भाषा में दिखाया जाएगा. जैसे, Pacific Daylight Time या Australian Eastern Daylight Time.

TimeZoneStatus

टाइम ज़ोन के जवाब वाले ऑब्जेक्ट में मौजूद status फ़ील्ड में, अनुरोध का स्टेटस होता है. status फ़ील्ड में ये वैल्यू हो सकती हैं:

  • OK का मतलब है कि अनुरोध स्वीकार कर लिया गया है.

  • INVALID_REQUEST का मतलब है कि अनुरोध का फ़ॉर्मैट सही नहीं है.

  • OVER_DAILY_LIMIT का मतलब इनमें से कोई एक है:

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

  • OVER_QUERY_LIMIT का मतलब है कि अनुरोध करने वाले व्यक्ति ने कोटा पार कर लिया है.

  • REQUEST_DENIED का मतलब है कि एपीआई ने अनुरोध पूरा नहीं किया. पक्का करें कि अनुरोध, एचटीटीपी के बजाय एचटीटीपीएस से भेजा गया हो.

  • UNKNOWN_ERROR का मतलब है कि कोई ऐसी गड़बड़ी हुई है जिसके बारे में जानकारी नहीं है.

  • ZERO_RESULTS का मतलब है कि तय की गई जगह या समय के लिए, टाइम ज़ोन का डेटा नहीं मिला. पक्का करें कि अनुरोध, पानी में मौजूद किसी जगह के लिए नहीं, बल्कि ज़मीन पर मौजूद किसी जगह के लिए हो.

स्थानीय समय का हिसाब लगाना

किसी जगह का स्थानीय समय, timestamp पैरामीटर और नतीजे में मौजूद dstOffset और rawOffset फ़ील्ड की वैल्यू का योग होता है.