दूरी का मैट्रिक्स एपीआई अनुरोध और उसका जवाब

परिचय

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

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

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

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

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

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

• डेस्टिनेशन

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

• ओरिजन

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

  • जगह का आईडी: अगर आपको जगह का आईडी देना है, तो आपको इसके पहले 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 को मौजूदा समय या आने वाले समय के लिए सेट किया जाना चाहिए. यह बीते हुए समय की नहीं हो सकती.
  ध्यान दें: अगर यात्रा शुरू करने का समय नहीं बताया गया है, तो रूट और अवधि का चुनाव, सड़क नेटवर्क और समय से अलग ट्रैफ़िक की औसत स्थितियों के आधार पर किया जाता है. सड़क नेटवर्क में बदलाव, ट्रैफ़िक की औसत स्थितियों के अपडेट होने, और सेवा के डिस्ट्रिब्यूटेड नेचर की वजह से, किसी अनुरोध के नतीजे समय के साथ अलग-अलग हो सकते हैं. इसके अलावा, एक जैसे रास्तों के लिए भी, नतीजे किसी भी समय या फ़्रीक्वेंसी के हिसाब से अलग-अलग हो सकते हैं.
  ध्यान दें: Distance Matrix API के उन अनुरोधों में, हर अनुरोध के लिए ज़्यादा से ज़्यादा 100 एलिमेंट शामिल किए जा सकते हैं जिनमें departure_time when mode=driving पैरामीटर का इस्तेमाल किया गया हो. ओरिजन की संख्या को डेस्टिनेशन की संख्या से गुणा करने पर, एलिमेंट की संख्या मिलती है.

• भाषा

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

  • इस्तेमाल की जा सकने वाली भाषाओं की सूची देखें. 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 से मिले जवाब में 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

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