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

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

डेटा पेलोड को पढ़ने की अनुमति

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

चालू ट्रिप के स्टेटस मॉनिटर करना

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

स्थिति	ब्यौरा
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 FeatureCollection में दिखाते हैं. यह डेटा, execution.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 पैरामीटर का इस्तेमाल करें, ताकि बड़े फ़ील्ड को शामिल न किया जा सके. ज़्यादा जानकारी के लिए, वैकल्पिक कॉन्फ़िगरेशन देखें.

रास्ते में हुए बदलावों को मैनेज करना (सिर्फ़ Waze के लिए)

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

• मांग पर: GetTrip तरीके को कॉल करें. सर्वर, आखिरी बार के विचलन की स्थिति को सेव करता है.
• रीयल-टाइम: Google Cloud Pub/Sub की सदस्यता लें. यह सेवा, updated_trip इवेंट का इस्तेमाल करके, बदलावों के बारे में सूचनाएं पब्लिश करती है. ऐसा, बदलाव का पता चलने के पांच सेकंड के अंदर किया जाता है.

विचलन पेलोड को पढ़ना

last_route_deviation ऑब्जेक्ट, इवेंट का विश्लेषण करने में आपकी मदद करने के लिए यह मेटाडेटा उपलब्ध कराता है.

फ़ील्ड	टाइप	ब्यौरा
location	LatLng	अक्षांश और देशांतर के वे निर्देशांक जहां क्लाइंट डिवाइस ने विचलन रिकॉर्ड किया.
source	TriggerSource	बदलाव की वजह. इसका इस्तेमाल करके यह पता लगाएं कि ड्राइवर ने कोई अनचाही कार्रवाई की है या सिस्टम के निर्देशों का पालन किया है: DRIVER_INITIATED_REROUTE: ड्राइवर ने जान-बूझकर कोई फ़ैसला लिया हो. उदाहरण के लिए, गलत मोड़ लेना या मैन्युअल तरीके से नया रास्ता चुनना. SYSTEM_INITIATED_REROUTE: नेविगेशन ऐप्लिकेशन ने नया रास्ता चुना है. उदाहरण के लिए, ऐसा ट्रैफ़िक की स्थिति बदलने या सड़क बंद होने की वजह से हो सकता है.
client_timestamp	Timestamp	वह समय जब क्लाइंट डिवाइस को बदलाव का पता चला.
server_timestamp	Timestamp	सर्वर ने विचलन के अपडेट को प्रोसेस करने में कितना समय लिया.

यात्रा खत्म होने की स्थितियों को मैनेज करना

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

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