यात्रा का डेटा मैनेज करना

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

डेटा पेलोड पढ़ना

Google Maps या Waze, यात्रा का डेटा पेलोड, Navigation Connect के सर्वर को भेजता है. यह डेटा, ड्राइवर के नेविगेशन शुरू करने पर, रास्ते में समय-समय पर (डिफ़ॉल्ट रूप से हर 60 सेकंड में) और ड्राइवर के मंज़िल पर पहुंचने पर भेजा जाता है. हर JSON मैसेज में, यात्रा से जुड़ा ज़रूरी डेटा होता है. इसमें, ड्राइवर के रास्ते के हिसाब से सटीक कोऑर्डिनेट, तय की गई दूरी, और पहुंचने का अनुमानित समय (ईटीए) शामिल होता है.

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

{
  "name": "projects/123456/trips/221B9CD6-4146-4CBF-9556-853817654938",
  "state": "ENROUTE",
  "execution": {
    "origin": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      }
    },
    "destination": {
      "point": {
        "latitude": 51.515598,
        "longitude": -0.1277623
      }
    },
    "location": {
      "point": {
        "latitude": 51.5333329,
        "longitude": -0.1265845
      },
      "sourceTime": "2025-05-30T12:37:26Z",
      "serverTime": "2025-05-30T12:37:26.221069Z"
    },
    "traveledDuration": "0s",
    "remainingDuration": "990s",
    "traveledDistanceMeters": 0,
    "remainingDistanceMeters": 2879,
    "stopAddedInRoute": false
  }
}

ध्यान दें: अगर आपको Google Cloud Pub/Sub का इस्तेमाल करके डेटा मिलता है, तो यह सेवा, यात्रा के अपडेट को स्टैंडर्ड मैसेज एनवलप में रैप करती है. डेटा फ़ील्ड में, Navigation Connect का असली JSON पेलोड होता है.

चालू यात्रा के स्टेटस पर नज़र रखना

यात्रा के सफलतापूर्वक शुरू होने की पुष्टि करने और उसकी प्रोग्रेस पर नज़र रखने के लिए, हर पेलोड में स्टेटस फ़ील्ड का आकलन करें.

स्टेटस	ब्यौरा
NEW	यात्रा शुरू हो गई है, लेकिन ड्राइवर ने अभी तक नेविगेशन शुरू नहीं किया है.
ENROUTE	ड्राइवर, मंज़िल तक पहुंचने के लिए नेविगेट कर रहा है. इस स्टेटस का इस्तेमाल करके, पुष्टि करें कि यात्रा की पुष्टि हो गई है और वह सफलतापूर्वक शुरू हो गई है.

जोड़े गए स्टॉप मैनेज करना

ड्राइवर, नेविगेशन के दौरान अपने रास्ते में स्टॉप जोड़ सकते हैं. अगर वे ऐसा करते हैं, तो Navigation Connect, JSON डेटा पेलोड में execution.stopAddedInRoute फ़ील्ड को true पर सेट कर देता है. Navigation Connect API, ड्राइवर को उसकी असली मंज़िल तक ट्रैक करता रहता है. जोड़े गए स्टॉप को शामिल करने के लिए, पहुंचने का अनुमानित समय (ईटीए), दूरी, और अवधि जैसी मेट्रिक बढ़ जाती हैं.

स्टॉप जोड़ने का तरीका, नेविगेशन ऐप्लिकेशन पर निर्भर करता है और यह उसकी स्टैंडर्ड सुविधा के मुताबिक होता है:

• Google Maps: ड्राइवर अपने रास्ते में एक से ज़्यादा स्टॉप जोड़ सकते हैं.
• Waze: ड्राइवर सिर्फ़ एक स्टॉप जोड़ सकते हैं. अगर कोई ड्राइवर दूसरा स्टॉप जोड़ने की कोशिश करता है, तो Waze उसे मौजूदा रास्ते में स्टॉप जोड़ने के बजाय, नया नेविगेशन सेशन शुरू करने के लिए कहता है.

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

पुष्टि करने और यात्रा शुरू करने से जुड़ी समस्याओं को हल करना

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

अगर स्टेटस NEW से बदलकर ENROUTE नहीं होता है, तो हो सकता है कि ड्राइवर का डिवाइस, पुष्टि करने की प्रोसेस को रोक रहा हो. Navigation Connect, इन मामलों में गड़बड़ी के मैसेज नहीं भेजता. इनकी पुष्टि करें:

• ड्राइवर के डिवाइस में Waze का 5.15.5 या इसके बाद का वर्शन या Google Maps का 26.14 या इसके बाद का वर्शन इंस्टॉल है.
• ड्राइवर, Android Auto या Apple CarPlay का इस्तेमाल नहीं कर रहा है.
• ड्राइवर के पास इंटरनेट कनेक्शन चालू है.

रास्ते के बाकी डेटा को मैनेज करना (सिर्फ़ Waze के लिए)

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

इस डेटा को इनजेस्ट और प्रोसेस करके, अपने ऐप्लिकेशन में कई सुविधाएं दी जा सकती हैं. इनमें ये उदाहरण शामिल हैं:

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

Navigation Connect, रास्ते की बाकी जानकारी को execution.remainingRoute फ़ील्ड में दिखाता है. भले ही, आपने GetTrip का अनुरोध भेजा हो या Google Cloud Pub/Sub का इस्तेमाल करके, इवेंट के हिसाब से अपडेट मिले हों. हालांकि, पेलोड इस डेटा को किस फ़ॉर्मैट और स्ट्रक्चर में दिखाता है, यह इस बात पर निर्भर करता है कि आपने डेटा पाने के लिए कौनसा तरीका इस्तेमाल किया है.

GetTrip तरीका

GetTrip तरीके को कॉल करने पर, पॉलीलाइन का रिस्पॉन्स फ़ॉर्मैट, आपके अनुरोध में बताए गए routePolylineFormat पैरामीटर पर निर्भर करता है. ज़्यादा जानकारी के लिए, पॉलीलाइन के फ़ॉर्मैट को पसंद के मुताबिक बनाना लेख पढ़ें.

पॉलीलाइन के सभी फ़ॉर्मैट के लिए, Navigation Connect, ट्रैफ़िक को execution.remainingRoute.trafficInformation फ़ील्ड में, SpeedReadingInterval ऑब्जेक्ट की अलग सूची के तौर पर दिखाता है. ये ऑब्जेक्ट, इन वैल्यू का इस्तेमाल करके, ट्रैफ़िक की कैटगरी को पॉलीलाइन इंडेक्स से मैप करते हैं:

• startPolylinePointIndex: पॉलीलाइन पर, ट्रैफ़िक इंटरवल का शुरुआती इंडेक्स.
• endPolylinePointIndex: ट्रैफ़िक इंटरवल का आखिरी इंडेक्स.
• speed: इस सेगमेंट के लिए ट्रैफ़िक की कैटगरी: NORMAL, SLOW या TRAFFIC_JAM.

Google Cloud Pub/Sub के अपडेट

Pub/Sub की मदद से यात्रा का डेटा पाने पर, अपडेट हमेशा एक ही GeoJSON में, रास्ते के बाकी डेटा को दिखाते हैं.FeatureCollectionexecution.remainingRoute

इस फ़ॉर्मैट में, पॉलीलाइन की ज्यामिति को सीधे तौर पर ट्रैफ़िक की स्पीड के साथ जोड़ा जाता है. इससे इंडेक्स को मैन्युअल तरीके से मैप करने की ज़रूरत नहीं होती.

Pub/Sub के पेलोड का उदाहरण देखना

यहां दिए गए कोड सैंपल में, Pub/Sub मैसेज के updatedTrip ऑब्जेक्ट में, execution.remainingRoute फ़ील्ड में दिखाया गया GeoJSON स्ट्रक्चर दिखता है:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.3934, 37.7955],
          [-122.4010, 37.7980]
        ]
      },
      "properties": {
        "speed": "SLOW"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.4010, 37.7980],
          [-122.4058, 37.8025],
          [-122.4187, 37.8021]
        ]
      },
      "properties": {
        "speed": "NORMAL"
      }
    }
  ]
}
    

पेलोड का साइज़ ऑप्टिमाइज़ करना

कोऑर्डिनेट के कलेक्शन बड़े होते हैं. इसलिए, Pub/Sub के मैसेज में रास्ते के बाकी डेटा को शामिल करने से, पेलोड का साइज़ काफ़ी बढ़ सकता है. यह हर मैसेज के लिए 13–14 केबी तक हो सकता है. अगर आपको बार-बार अपडेट मिलते हैं, तो इससे बैकएंड के प्रोसेसिंग लोड और इस्तेमाल की लागत बढ़ सकती है.

अपनी स्ट्रीम को ऑप्टिमाइज़ करने के लिए, यात्रा शुरू करते समय, TripConfig ऑब्जेक्ट में pubsubFieldMask पैरामीटर का इस्तेमाल करें. इससे बड़े फ़ील्ड शामिल नहीं होंगे. ज़्यादा जानकारी के लिए, वैकल्पिक कॉन्फ़िगरेशन देखें.

यात्रा के खत्म होने के स्टेटस को मैनेज करना

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

स्टेटस	ब्यौरा	सुझाई गई कार्रवाई
ARRIVED	ड्राइवर, मंज़िल पर पहुंच गया है.	remainingDistanceMeters देखें. अगर ड्राइवर ने आस-पास कहीं गाड़ी पार्क की है , लेकिन सटीक कोऑर्डिनेट पर नहीं, तो अपने ऐप्लिकेशन में पैदल चलने के निर्देश देने पर विचार करें.
SUSPENDED	ड्राइवर, मंज़िल पर पहुंचने से पहले ही, मैन्युअल तरीके से रास्ते के दिशा-निर्देश से बाहर निकल गया है. Google Maps या Waze, सेशन से जल्दी बाहर निकलने पर, ड्राइवर को आपके ऐप्लिकेशन पर अपने-आप वापस नहीं भेजता. इसलिए, ड्राइवर को मैन्युअल तरीके से वापस जाने वाले बटन पर टैप करना होगा. ध्यान दें: अगर ड्राइवर, चालू नेविगेशन सेशन से बाहर निकले बिना, आपके ऐप्लिकेशन पर वापस जाने के लिए, वापस जाने वाले बटन का इस्तेमाल करता है, तो यात्रा का स्टेटस ENROUTE ही रहता है. ज़्यादा जानकारी के लिए, यात्रा के बीच में ऐप्लिकेशन बदलने की सुविधा को मैनेज करना लेख पढ़ें.	ड्राइवर को अपनी यात्रा पूरी करने में मदद करने के लिए, execution.location की तुलना मंज़िल से करें. अगर दूरी बाकी है, तो यात्रा जारी रखने या पैदल चलने के मोड पर स्विच करने के लिए, बटन या लिंक दें.
FAILED	तकनीकी गड़बड़ी की वजह से, कनेक्शन में रुकावट आई है. ऐसा तब होता है, जब ऐप्लिकेशन किसी रास्ते का हिसाब नहीं लगा पाता या सुरक्षा से जुड़ा कोई चेतावनी मैसेज दिखता है. ऐसा हो सकता है कि ड्राइवर अब भी नेविगेट कर रहा हो, लेकिन आपको अपडेट नहीं मिलेंगे.	अपने ऐप्लिकेशन में, स्टेटस को मैन्युअल तरीके से ट्रैक करने की सुविधा पर वापस जाएं.
CLIENT_ERROR	यह स्टेटस, इनमें से किसी एक वजह से दिखता है: ड्राइवर, सहमति वापस ले लेता है. ड्राइवर, Android Auto या Apple CarPlay जैसे ऐसे प्लैटफ़ॉर्म का इस्तेमाल करता है जो काम नहीं करता. आपका ऐप्लिकेशन, किसी ऐसी यात्रा के लिए यात्रा के टोकन का फिर से इस्तेमाल करता है जिसकी मंज़िल अलग है. यात्रा के दौरान, ड्राइवर किसी भी समय अमेरिका में होता है. हालांकि, सेटअप के दौरान अपने ऐप्लिकेशन की पुष्टि करते समय, आपके ऐप्लिकेशन में अमेरिका में डेटा शेयर करने की सुविधा चालू नहीं होती.	अपने ऐप्लिकेशन में, स्टेटस को मैन्युअल तरीके से ट्रैक करने की सुविधा पर वापस जाएं.