Distance Matrix API (लेगसी) का अनुरोध और रिस्पॉन्स

परिचय

Distance Matrix API (लेगसी) का अनुरोध इस तरह किया जाता है:

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

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

• json (सुझाया गया) से पता चलता है कि आउटपुट, JavaScript ऑब्जेक्ट Notation (JSON) में है.
• xml से पता चलता है कि आउटपुट एक्सएमएल फ़ॉर्मैट में है.

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

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

• डेस्टिनेशन

  एक या उससे ज़्यादा ऐसी जगहें जिन्हें यात्रा की दूरी और समय का हिसाब लगाने के लिए, आखिरी पॉइंट के तौर पर इस्तेमाल किया जा सकता है. destinations पैरामीटर के विकल्प, origins पैरामीटर के विकल्पों के जैसे ही होते हैं.

• ओरिजन

  यात्रा की दूरी और समय का हिसाब लगाने के लिए यात्रा शुरू करने की जगह. पाइप वर्ण (|) से अलग करके, एक या एक से ज़्यादा जगहों की जानकारी दी जा सकती है. यह जानकारी, जगह के आईडी, पते या अक्षांश/देशांतर के निर्देशांक के तौर पर दी जा सकती है:

  • जगह का आईडी: अगर आपको जगह का आईडी देना है, तो आपको उसके पहले place_id: जोड़ना होगा.
  • पता: अगर कोई पता पास किया जाता है, तो सेवा उस स्ट्रिंग को जियोकोड करती है और दूरी का हिसाब लगाने के लिए, उसे अक्षांश/देशांतर के निर्देशांक में बदल देती है. यह कोऑर्डिनेट, Geocoding API से मिले कोऑर्डिनेट से अलग हो सकता है. उदाहरण के लिए, किसी इमारत के बीच के हिस्से के बजाय उसके प्रवेश द्वार का कोऑर्डिनेट.
    ध्यान दें: पते या अक्षांश/देशांतर के निर्देशांकों का इस्तेमाल करने के बजाय, जगह के आईडी का इस्तेमाल करना बेहतर होता है. निर्देशांकों का इस्तेमाल करने पर, पॉइंट हमेशा उन निर्देशांकों के सबसे नज़दीकी सड़क पर स्नैप हो जाएगा. ऐसा हो सकता है कि यह सड़क, प्रॉपर्टी का ऐक्सेस पॉइंट न हो या ऐसी सड़क न हो जो आपको जल्दी या सुरक्षित तरीके से डेस्टिनेशन तक पहुंचा सके. पते का इस्तेमाल करने पर, आपको बिल्डिंग के बीच की दूरी की जानकारी मिलेगी. हालांकि, बिल्डिंग के किसी भी दरवाज़े की दूरी की जानकारी नहीं मिलेगी.
  • निर्देशांक: अक्षांश/देशांतर निर्देशांक पास करने पर, वे सबसे नज़दीकी सड़क पर स्नैप हो जाएंगे. प्लेस आईडी पास करना बेहतर होता है. अगर आपको निर्देशांक पास करने हैं, तो पक्का करें कि अक्षांश और देशांतर की वैल्यू के बीच कोई खाली जगह न हो.
  • प्लस कोड को ग्लोबल कोड या कंपाउंड कोड के तौर पर फ़ॉर्मैट किया जाना चाहिए. प्लस कोड को यहां दिखाए गए फ़ॉर्मैट में लिखें. प्लस के निशान को यूआरएल के लिए कोड में बदलकर %2B और स्पेस को यूआरएल के लिए कोड में बदलकर %20 लिखा जाता है:
    • ग्लोबल कोड, चार वर्णों वाला एरिया कोड होता है. साथ ही, यह छह या इससे ज़्यादा वर्णों वाला लोकल कोड होता है (849VCWC8+R9 को 849VCWC8%2BR9 के तौर पर कोड किया जाता है).
    • कंपाउंड कोड, छह या इससे ज़्यादा वर्णों वाला लोकल कोड होता है. इसमें जगह की जानकारी साफ़ तौर पर दी जाती है (CWC8+R9 Mountain View, CA, USA को CWC8%2BR9%20Mountain%20View%20CA%20USA के तौर पर कोड किया जाता है).
  • कोड में बदली गई पॉलीलाइन इसके अलावा, कोड में बदली गई पॉलीलाइन के एल्गोरिदम का इस्तेमाल करके, कोड में बदले गए कोऑर्डिनेट का सेट दिया जा सकता है. अगर आपके पास कई ऑरिजिन पॉइंट हैं, तो यह सुविधा खास तौर पर काम आती है. इसकी वजह यह है कि कोड में बदली गई पॉलीलाइन का इस्तेमाल करने पर, यूआरएल काफ़ी छोटा हो जाता है.
    • कोड में बदली गई पॉलीलाइन के नाम से पहले enc: और उसके बाद कोलन : जोड़ना ज़रूरी है. उदाहरण के लिए: origins=enc:gfo}EtohhU:
    • पाइप वर्ण | का इस्तेमाल करके, एक से ज़्यादा एन्कोड की गई पॉलीलाइन भी शामिल की जा सकती हैं. उदाहरण के लिए:

      origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
      

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

• arrival_time

  यह विकल्प, ट्रांज़िट के निर्देशों के लिए पहुंचने का पसंदीदा समय बताता है. यह समय, 1 जनवरी, 1970 को आधी रात के बाद से सेकंड में होता है. departure_time या arrival_time में से किसी एक को तय किया जा सकता है, लेकिन दोनों को नहीं. ध्यान दें कि arrival_time को पूर्णांक के तौर पर तय किया जाना चाहिए.

• बचना

  दूरी का हिसाब लगाते समय, कुछ पाबंदियों का पालन किया जा सकता है. पाबंदियों के बारे में बताने के लिए, avoid पैरामीटर का इस्तेमाल किया जाता है. साथ ही, इस पैरामीटर के लिए एक ऐसा तर्क दिया जाता है जिससे यह पता चलता है कि किस पाबंदी से बचना है. इन पाबंदियों को लागू किया जा सकता है:

  • tolls से पता चलता है कि कैलकुलेट किए गए रास्ते में टोल वाली सड़कें/पुल शामिल नहीं होने चाहिए.
  • highways से पता चलता है कि कैलकुलेट किए गए रास्ते में हाइवे शामिल नहीं होने चाहिए.
  • ferries से पता चलता है कि कैलकुलेट किए गए रास्ते में फ़ेरी शामिल नहीं होनी चाहिए.
  • indoor से पता चलता है कि कैलकुलेट किए गए रास्ते में, पैदल चलने और बस, मेट्रो वगैरह के रास्ते के लिए निर्देश के लिए, घर के अंदर की सीढ़ियों का इस्तेमाल नहीं किया जाना चाहिए.

  टोल, हाइवे, और फ़ेरी वाले रास्तों से बचने के लिए, एक साथ अनुरोध किया जा सकता है. इसके लिए, avoid पैरामीटर को दोनों पाबंदियां पास करनी होंगी. उदाहरण के लिए, avoid=tolls|highways|ferries.

  ध्यान दें: पाबंदियां जोड़ने से, उन रास्तों को नहीं हटाया जाता जिनमें प्रतिबंधित सुविधा शामिल है. इससे नतीजे, ज़्यादा फ़ायदेमंद रास्तों के हिसाब से दिखते हैं.

• departure_time

  इससे यात्रा शुरू करने का पसंदीदा समय तय किया जाता है. समय को पूर्णांक के तौर पर सेट किया जा सकता है. यह पूर्णांक, 1 जनवरी, 1970 को आधी रात के बाद से सेकंड में होता है. अगर 9999-12-31T23:59:59.999999999Z के बाद की departure_time तय की जाती है, तो एपीआई departure_time को 9999-12-31T23:59:59.999999999Z पर वापस सेट कर देगा. इसके अलावा, अब की वैल्यू भी दी जा सकती है. इससे, रवाना होने का समय मौजूदा समय पर सेट हो जाता है. यह समय, सेकंड के हिसाब से सटीक होता है. रवानगी का समय दो मामलों में बताया जा सकता है:

  • यात्रा के लिए सार्वजनिक परिवहन का इस्तेमाल करने के अनुरोधों के लिए: departure_time या arrival_time में से किसी एक को वैकल्पिक तौर पर तय किया जा सकता है. अगर दोनों में से कोई भी समय नहीं दिया गया है, तो departure_time की डिफ़ॉल्ट वैल्यू, अभी का समय होती है. इसका मतलब है कि डिफ़ॉल्ट रूप से, बस के रवाना होने का समय, मौजूदा समय होता है.
  • ड्राइविंग मोड में यात्रा करने के अनुरोधों के लिए: departure_time तय किया जा सकता है, ताकि आपको ट्रैफ़िक का हाल को ध्यान में रखते हुए, यात्रा के रास्ते और अवधि (जवाब वाला फ़ील्ड: duration_in_traffic) की जानकारी मिल सके. departure_time को मौजूदा समय या आने वाले समय के लिए सेट किया जाना चाहिए. यह बीता हुआ समय नहीं हो सकता.
  ध्यान दें: अगर यात्रा शुरू करने का समय नहीं बताया जाता है, तो रास्ते और अवधि का चुनाव सड़क नेटवर्क और समय के हिसाब से ट्रैफ़िक की औसत स्थितियों के आधार पर किया जाता है. सड़क नेटवर्क में बदलाव, ट्रैफ़िक का हाल अपडेट होने, और सेवा के डिस्ट्रिब्यूटेड नेचर की वजह से, किसी अनुरोध के नतीजे समय के साथ अलग-अलग हो सकते हैं. लगभग एक जैसे रास्तों के लिए, नतीजे किसी भी समय या फ़्रीक्वेंसी पर अलग-अलग हो सकते हैं.
  ध्यान दें: डिस्टेंस मैट्रिक्स के अनुरोधों में departure_time when mode=driving की जानकारी देने पर, हर अनुरोध में ज़्यादा से ज़्यादा 100 एलिमेंट शामिल किए जा सकते हैं. शुरुआत की जगहों की संख्या और मंज़िलों की संख्या को गुणा करने पर, एलिमेंट की संख्या मिलती है.

• भाषा

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

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

• मोड

  दूरी और दिशाओं का हिसाब लगाने के लिए, यात्रा के तरीके के बारे में बताया जा सकता है. डिफ़ॉल्ट रूप से, DRIVING मोड का इस्तेमाल किया जाता है. डिफ़ॉल्ट रूप से, दिशा-निर्देशों को ड्राइविंग के लिए रास्ते के निर्देश के तौर पर कैलकुलेट किया जाता है. यात्रा के इन तरीकों के लिए, यह सुविधा काम करती है:

  • driving (डिफ़ॉल्ट) से सड़क नेटवर्क का इस्तेमाल करके, ड्राइविंग के लिए रास्ते के निर्देश या दूरी का पता चलता है.
  • walking पैदल चलने के लिए रास्ते और फ़ुटपाथ (जहां उपलब्ध हों) का इस्तेमाल करके, पैदल चलने के रास्ते या दूरी के बारे में अनुरोध करता है.
  • bicycling साइकल से यात्रा करने के लिए दिशा-निर्देश या दूरी का अनुरोध करता है. इसके लिए, साइकल के रास्ते और पसंदीदा सड़कों (जहां उपलब्ध हो) का इस्तेमाल किया जाता है.
  • transit सार्वजनिक परिवहन के रास्तों का इस्तेमाल करके, दिशा-निर्देश या दूरी का अनुरोध करता है (जहां यह सुविधा उपलब्ध है). अगर आपने मोड को ट्रांज़िट पर सेट किया है, तो आपके पास departure_time या arrival_time में से किसी एक को तय करने का विकल्प होता है. अगर दोनों में से कोई भी समय नहीं दिया गया है, तो departure_time की डिफ़ॉल्ट वैल्यू 'अभी' होती है. इसका मतलब है कि रवाना होने का समय, डिफ़ॉल्ट रूप से मौजूदा समय पर सेट होता है. आपके पास transit_mode और/या transit_routing_preference को शामिल करने का विकल्प भी होता है.
  ध्यान दें: पैदल चलने और साइकल चलाने के लिए दिए गए निर्देशों में, कभी-कभी पैदल चलने या साइकल चलाने के लिए बने रास्ते शामिल नहीं होते. इसलिए, इन निर्देशों के जवाब में चेतावनियां दिखेंगी. आपको ये चेतावनियां उपयोगकर्ता को दिखानी होंगी.
  ध्यान दें: ट्रांज़िट यात्राओं की जानकारी, पिछले सात दिनों या आने वाले 100 दिनों तक के लिए उपलब्ध होती है. हालांकि, यह जानकारी डेटा उपलब्ध कराने वाली कंपनियों से मिली जानकारी के आधार पर उपलब्ध होती है. बस, मेट्रो वगैरह के शेड्यूल में अक्सर बदलाव होता रहता है. इसलिए, समय के साथ-साथ यात्रा के लिए उपलब्ध बस, मेट्रो वगैरह की जानकारी में भी बदलाव हो सकता है. साथ ही, यह भी ज़रूरी नहीं है कि बहुत पहले से किए गए अनुमानों के नतीजे हमेशा एक जैसे हों.

• प्रांत

  क्षेत्र का कोड, जिसे दो वर्णों वाली ccTLD ("टॉप-लेवल डोमेन") वैल्यू के तौर पर तय किया जाता है. ज़्यादातर ccTLD कोड, ISO 3166-1 कोड के जैसे ही होते हैं. हालांकि, कुछ अपवाद भी हैं. उदाहरण के लिए, यूनाइटेड किंगडम का ccTLD "uk" (.co.uk) है, जबकि इसका ISO 3166-1 कोड "gb" है. तकनीकी तौर पर, यह "यूनाइटेड किंगडम ऑफ़ ग्रेट ब्रिटेन और नॉर्दर्न आयरलैंड" के लिए है.

• traffic_model

  इस विकल्प से, ट्रैफ़िक में लगने वाले समय का हिसाब लगाते समय इस्तेमाल की जाने वाली मान्यताओं के बारे में पता चलता है. इस सेटिंग से, जवाब में duration_in_traffic फ़ील्ड में दिखाई गई वैल्यू पर असर पड़ता है. इस फ़ील्ड में, ट्रैफ़िक में लगने वाले अनुमानित समय की जानकारी होती है. यह जानकारी, अब तक के औसत समय के आधार पर दी जाती है. traffic_model पैरामीटर सिर्फ़ ड्राइविंग के लिए रास्ते के निर्देशों के लिए तय किया जा सकता है. इसके लिए, अनुरोध में departure_time शामिल होना चाहिए. इस पैरामीटर के लिए ये वैल्यू उपलब्ध हैं:

  • best_guess (डिफ़ॉल्ट) से पता चलता है कि लौटाए गए duration_in_traffic की वैल्यू, यात्रा में लगने वाले समय का सबसे सही अनुमान होना चाहिए. यह अनुमान, ट्रैफ़िक की पुरानी स्थितियों और लाइव ट्रैफ़िक, दोनों के बारे में उपलब्ध जानकारी के आधार पर लगाया जाता है. लाइव ट्रैफ़िक की जानकारी, departure_time के मौजूदा समय के जितना करीब होगी उतनी ही ज़्यादा अहम होगी.
  • pessimistic से पता चलता है कि लौटाए गए duration_in_traffic की वैल्यू, ज़्यादातर दिनों में यात्रा में लगने वाले असल समय से ज़्यादा होनी चाहिए. हालांकि, कभी-कभी ट्रैफ़िक की स्थिति बहुत खराब होने पर, यह वैल्यू इससे ज़्यादा हो सकती है.
  • optimistic से पता चलता है कि ट्रैफ़िक में लगने वाला समय, ज़्यादातर दिनों में यात्रा में लगने वाले असल समय से कम होना चाहिए. हालांकि, कभी-कभी ट्रैफ़िक का हाल अच्छा होने पर, यात्रा में लगने वाला समय इस वैल्यू से कम हो सकता है.

  best_guess की डिफ़ॉल्ट वैल्यू से, इस्तेमाल के ज़्यादातर उदाहरणों के लिए सबसे काम के अनुमान मिलेंगे. ऐसा हो सकता है कि best_guess में यात्रा में लगने वाले समय का अनुमान, optimistic से कम हो या pessimistic से ज़्यादा हो. ऐसा इसलिए होता है, क्योंकि best_guess का अनुमान लगाने वाला मॉडल, लाइव ट्रैफ़िक की जानकारी को इंटिग्रेट करता है.

• transit_mode

  इससे ट्रांज़िट के एक या उससे ज़्यादा पसंदीदा मोड के बारे में पता चलता है. इस पैरामीटर का इस्तेमाल सिर्फ़ बस, मेट्रो वगैरह से जुड़ी दिशाओं के लिए किया जा सकता है. यह पैरामीटर, इन आर्ग्युमेंट के साथ काम करता है:

  • bus से पता चलता है कि कैलकुलेट किए गए रूट में बस से यात्रा करने को प्राथमिकता दी जानी चाहिए.
  • subway से पता चलता है कि कैलकुलेट किए गए रास्ते में, मेट्रो से यात्रा करने को प्राथमिकता दी जानी चाहिए.
  • train से पता चलता है कि कैलकुलेट किए गए रास्ते में ट्रेन से यात्रा करने को प्राथमिकता दी जानी चाहिए.
  • tram से पता चलता है कि कैलकुलेट किए गए रास्ते में, ट्रैम और लाइट रेल से यात्रा करने को प्राथमिकता दी जानी चाहिए.
  • rail से पता चलता है कि कैलकुलेट किए गए रास्ते में ट्रेन, ट्राम, लाइट रेल, और सबवे से यात्रा करने को प्राथमिकता दी जानी चाहिए. यह transit_mode=train|tram|subway के बराबर है.

• transit_routing_preference

  इससे बस, मेट्रो वगैरह के रास्तों के लिए प्राथमिकताएं तय की जाती हैं. इस पैरामीटर का इस्तेमाल करके, एपीआई की ओर से चुने गए डिफ़ॉल्ट सबसे अच्छे रास्ते को स्वीकार करने के बजाय, लौटाए गए विकल्पों को प्राथमिकता दी जा सकती है. इस पैरामीटर को सिर्फ़ बस, मेट्रो वगैरह से यात्रा करने के निर्देशों के लिए सेट किया जा सकता है. यह पैरामीटर, इन आर्ग्युमेंट के साथ काम करता है:

  • less_walking का मतलब है कि कैलकुलेट किए गए रास्ते में पैदल चलने की दूरी कम होनी चाहिए.
  • fewer_transfers से पता चलता है कि कैलकुलेट किए गए रास्ते में, वाहन बदलने की संख्या कम होनी चाहिए.

• इकाइयां

  नतीजे दिखाते समय, इस्तेमाल किए जाने वाले यूनिट सिस्टम के बारे में बताता है.

  ध्यान दें: इकाई सिस्टम की इस सेटिंग का असर सिर्फ़ दूरी वाले फ़ील्ड में दिखने वाले टेक्स्ट पर पड़ता है. दूरी वाले फ़ील्ड में ऐसी वैल्यू भी होती हैं जो हमेशा मीटर में दिखाई जाती हैं.

अनुरोध के उदाहरण

इस उदाहरण में, डेस्टिनेशन के निर्देशांकों के बारे में बताने के लिए, अक्षांश/देशांतर के निर्देशांकों का इस्तेमाल किया गया है:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

इस उदाहरण में, डेस्टिनेशन के निर्देशांकों के बारे में बताने के लिए प्लस कोड का इस्तेमाल किया गया है:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

इस उदाहरण में, एन्कोड की गई पॉलीलाइन का इस्तेमाल करके एक ही अनुरोध दिखाया गया है:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

ट्रैफ़िक जानकारी

ट्रैफ़िक की जानकारी का इस्तेमाल तब किया जाता है, जब ये सभी शर्तें पूरी होती हैं. ये शर्तें, Distance Matrix API के जवाब में duration_in_traffic फ़ील्ड पाने के लिए ज़रूरी हैं:

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

इसके अलावा, अपने अनुरोध में traffic_model पैरामीटर शामिल किया जा सकता है. इससे यह तय किया जा सकता है कि ट्रैफ़िक में लगने वाले समय का हिसाब लगाते समय किन मान्यताओं का इस्तेमाल किया जाए.

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

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins
   
  
 

जगह के हिसाब से बिड मॉडिफ़ायर

जगह की जानकारी में बदलाव करने वाले शब्दों का इस्तेमाल करके, यह बताया जा सकता है कि ड्राइवर को किसी जगह पर कैसे पहुंचना चाहिए. इसके लिए, side_of_road मॉडिफ़ायर का इस्तेमाल करके यह बताया जा सकता है कि सड़क के किस ओर चलना है. इसके अलावा, हेडिंग तय करके यह बताया जा सकता है कि किस दिशा में जाना है.

यह तय करना कि कैलकुलेट किए गए रास्ते, सड़क के किसी खास हिस्से से होकर गुज़रें

किसी जगह की जानकारी देते समय, यह अनुरोध किया जा सकता है कि कैलकुलेट किया गया रास्ता, सड़क के उस हिस्से से होकर गुज़रे जिस तरफ़ वेपॉइंट है. इसके लिए, side_of_road: प्रीफ़िक्स का इस्तेमाल करें. उदाहरण के लिए, इस अनुरोध से लंबे रास्ते की दूरी का पता चलेगा, ताकि वाहन सड़क के उस किनारे पर रुक सके जिस ओर वेपॉइंट को झुकाया गया था:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

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

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

side_of_road: मॉडिफ़ायर का इस्तेमाल सिर्फ़ इस पाबंदी के साथ किया जा सकता है:

• यात्रा का mode पैरामीटर driving है या इसे तय नहीं किया गया है (driving यात्रा का डिफ़ॉल्ट मोड है).

यह तय करना कि कैलकुलेट किए गए रास्तों का हेडिंग क्या होना चाहिए

किसी जगह के बारे में बताते समय, यह अनुरोध किया जा सकता है कि कैलकुलेट किया गया रास्ता, किसी खास हेडिंग में मौजूद जगह से होकर गुज़रे. इस हेडिंग को heading=X: प्रीफ़िक्स के साथ तय किया जाता है. इसमें X, 0 (शामिल) और 360 (शामिल नहीं) के बीच की पूर्णांक डिग्री वैल्यू होती है. हेडिंग 0 का मतलब उत्तर, 90 का मतलब पूरब, और इसी तरह घड़ी की दिशा में आगे बढ़ते जाना है. उदाहरण के लिए, इस अनुरोध में कैलकुलेट किया गया रूट, ऑरिजिन से पूरब की ओर जाता है. इसके बाद, यू-टर्न लेता है:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

heading=X: मॉडिफ़ायर का इस्तेमाल सिर्फ़ इन पाबंदियों के साथ किया जा सकता है:

• यात्रा का mode पैरामीटर driving, bicycling है या इसे तय नहीं किया गया है (driving, यात्रा का डिफ़ॉल्ट मोड है).
• side_of_road मॉडिफ़ायर को एक ही जगह के लिए सेट नहीं किया गया है.
• जगह की जानकारी, अक्षांश/देशांतर की वैल्यू के साथ दी जाती है. पतों, जगह के आईडी या कोड में बदली गई पॉलीलाइन के साथ heading का इस्तेमाल नहीं किया जा सकता.

Distance Matrix API के लिए अनुरोध और जवाब

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

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

इस अनुरोध से चार एलिमेंट मिलेंगे. इनमें दो ओरिजन और दो डेस्टिनेशन शामिल हैं:

नतीजे पंक्तियों में दिखाए जाते हैं. हर पंक्ति में, एक ऑरिजिन और हर डेस्टिनेशन की जानकारी होती है.

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km
   
  
 

DistanceMatrixResponse

DistanceMatrixStatus

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

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

DistanceMatrixRow

DistanceMatrixElement

किराया

रास्ते का कुल किराया.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}

DistanceMatrixElementStatus

• OK से पता चलता है कि जवाब में मान्य नतीजा शामिल है.
• NOT_FOUND का मतलब है कि इस पेयरिंग के ऑरिजिन और/या डेस्टिनेशन को जियोकोड नहीं किया जा सका.
• ZERO_RESULTS का मतलब है कि यात्रा शुरू करने की जगह और मंज़िल के बीच कोई रास्ता नहीं मिला.
• MAX_ROUTE_LENGTH_EXCEEDED का मतलब है कि अनुरोध किया गया रास्ता बहुत लंबा है और उसे प्रोसेस नहीं किया जा सकता.

TextValueObject

यह एक ऐसा ऑब्जेक्ट है जिसमें संख्या वाली वैल्यू और उसका फ़ॉर्मैट किया गया टेक्स्ट होता है.