טיפול בנתוני נסיעות

כשאתם מאחזרים את נתוני הנסיעה, הקצה העורפי מקבל מטענים ייעודיים (payloads) בפורמט JSON שמפרטים את התקדמות הנסיעה של הנהג. מנתחים את המטענים הייעודיים האלה כדי לעקוב אחרי הנסיעה, לעדכן את מערכות השילוח ולפרש את הסטטוסים הנוכחיים של הנסיעה, כדי לקבוע את השלב הבא של הנהג ככל שהנסיעה מתקדמת או כשהיא מסתיימת.

קריאת נתוני הפרוטוקולים

מפות Google או Waze שולחות את המטען הייעודי (payload) של נתוני הנסיעה לשרתי Navigation Connect כשהנהג מתחיל לנווט, מדי פעם לאורך המסלול (כל 60 שניות כברירת מחדל) וכשהנהג מגיע ליעד. כל הודעת JSON מכילה נתוני נסיעה רלוונטיים, כולל הקואורדינטות של הנהג שהוצמדו לכביש, המרחק שנסע וזמן ההגעה המשוער (ETA). העדכונים האלה משקפים את המסלול הפעיל של הנהג בזמן אמת, ולכן הם עשויים להיות שונים ממסלולים שחושבו מראש על ידי ה-backend (ראו שאלות נפוצות).

דוגמת הקוד הבאה מציגה מטען ייעודי (payload) של נתוני נסיעה, כשנהג מתחיל ניווט לנסיעה מ-King's Cross ל-Central St. Giles.

{
  "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
  }
}

מעקב אחרי סטטוסים של נסיעות פעילות

כדי לוודא שההפעלה הצליחה ולעקוב אחרי ההתקדמות, בודקים את השדה state בכל מטען ייעודי (payload).

סטטוס תיאור
NEW הנסיעה נוצרה, אבל הנהג עדיין לא התחיל לנווט.
ENROUTE הנהג מנווט באופן פעיל אל היעד. הסטטוס הזה מאשר שהנסיעה אומתה והתחילה בהצלחה.

טיפול בעצירות ביניים שנוספו

הנהגים יכולים להוסיף עצירות למסלול במהלך הניווט. אם כן, Navigation Connect מגדיר את השדה execution.stopAddedInRoute לערך true במטען הייעודי (payload) של נתוני ה-JSON. ‫Navigation Connect API ממשיך לעקוב אחרי הנהג בדרך ליעד המקורי. מדדים כמו זמן הגעה משוער (ETA), מרחק ומשך זמן גדלים כדי לכלול את העצירות שנוספו.

האופן שבו מוסיפים עצירות תלוי באפליקציית הניווט ומתאים לפונקציונליות הרגילה שלה:

  • מפות Google: הנהגים יכולים להוסיף כמה עצירות למסלול שלהם.
  • ‫Waze: נהגים יכולים להוסיף רק עצירה אחת. אם נהג מנסה להוסיף עוד עצירה, Waze מבקשת ממנו להתחיל סשן ניווט חדש במקום להוסיף את העצירה למסלול הנוכחי.

אתם לא צריכים לשנות את הקלט בקצה העורפי כדי לתמוך בתכונה הזו.

פתרון בעיות באימות ובאתחול

אם לא קיבלתם סטטוס ENROUTE, כנראה שהייתה שגיאת אימות. הסיבות הנפוצות כוללות שגיאות כתיב בפרמטרים של ה-API או אסימון נסיעה שפג תוקפו. בודקים את זמן התפוגה של האסימון בתגובה הראשונית של CreateTrip.

אם הסטטוס לא משתנה מ-NEW ל-ENROUTE, יכול להיות שהמכשיר של הנהג מונע את האימות. במקרים כאלה, Navigation Connect לא שולח הודעות שגיאה. בודקים את הדברים הבאים:

  • במכשיר של הנהג מותקנת אפליקציית Waze מגרסה 5.15.5 ואילך, או אפליקציית מפות Google מגרסה 26.14 ואילך.
  • הנהג לא משתמש ב-Android Auto או ב-Apple CarPlay.
  • לנהג יש חיבור פעיל לאינטרנט.

טיפול בשאר נתוני המסלול

אם הפעלתם דיווח על המסלול שנותר במהלך יצירת הנסיעה, הקצה העורפי מקבל את הקו הפוליגוני של המסלול שנותר ואת מצב התנועה בזמן אמת מהמיקום הנוכחי של הנהג ועד ליעד הסופי. הנהגים צריכים להתקין את גרסה 5.20.0.2 ומעלה של Waze ב-Android, את גרסה 5.20.0.1 ומעלה ב-iOS או את גרסה 26.27 ומעלה של מפות Google ל-Android.

אתם יכולים להטמיע ולעבד את הנתונים האלה כדי להפעיל כמה תכונות באפליקציות שלכם, כולל הדוגמאות הבאות:

  • מפות למעקב בזמן אמת: עיבוד הקו הפוליגוני של המסלול שנותר במפה באינטרנט או בנייד שמוצגת ללקוח, כדי לספק לו מידע על הנסיעה של הנהג.
  • שיפור הדיוק של זמן ההגעה המשוער: שילוב של הקו הפוליגוני שמוצמד לכביש ומהירויות מרווחי התנועה כדי לשפר את הלוגיסטיקה הפנימית או את התחזיות של זמני ההגעה של המשלוחים.
  • ניתוח התאימות של המסלול: משווים בין הגיאומטריה של המסלול שנותר לבין המסלולים הצפויים של השילוח כדי להעריך את מידת ההיצמדות של הנהג למסלול (בשאלות הנפוצות מוסבר למה יכולים להיות הבדלים בין מסלולים בזמן אמת לבין מסלולים שחושבו מראש).

‫Navigation Connect מחזיר את פרטי המסלול שנותרו בשדה execution.remainingRoute, בין אם אתם שולחים בקשת GetTrip ובין אם אתם מקבלים עדכונים מבוססי-אירועים באמצעות Google Cloud Pub/Sub. עם זאת, הפורמט והמבנה של הנתונים האלה ב-payload תלויים בשיטת האחזור שבה אתם משתמשים.

אמצעי תשלום אחד (GetTrip)

כשקוראים ל-method‏ GetTrip, פורמט התגובה של הקו הפוליגוני תלוי בפרמטר routePolylineFormat שציינתם בבקשה. מידע נוסף מופיע במאמר התאמה אישית של פורמטים של קווים פוליגוניים.

בכל הפורמטים של קווים פוליגוניים, Navigation Connect מחזיר את התנועה כרשימה נפרדת של אובייקטים מסוג SpeedReadingInterval בשדה execution.remainingRoute.trafficInformation. האובייקטים האלה ממפים קטגוריות של תנועה לאינדקסים של הקו הפוליגוני באמצעות הערכים הבאים:

  • startPolylinePointIndex: האינדקס ההתחלתי של מרווח התנועה בקו הפוליגוני.
  • ‫endPolylinePointIndex: האינדקס הסופי של מרווח הזמן של התנועה.
  • speed: קטגוריית התנועה של הפלח הזה: NORMAL,‏ SLOW או TRAFFIC_JAM.

עדכונים של Google Cloud Pub/Sub

כשמאחזרים נתוני נסיעה באמצעות Pub/Sub, העדכונים תמיד מחזירים את נתוני המסלול שנותרו ב-FeatureCollection מאוחד של GeoJSON בשדה execution.remainingRoute.

הפורמט הזה משלב את הגיאומטריה של הקו הפוליגוני ישירות עם מהירויות התנועה, וכך אין צורך למפות אינדקסים באופן ידני.

דוגמה למטען ייעודי (payload) של Pub/Sub

דוגמת הקוד הבאה מראה את מבנה ה-GeoJSON שמוחזר בשדה execution.remainingRoute בתוך האובייקט updatedTrip של הודעת Pub/Sub:

{
  "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"
      }
    }
  ]
}
    

אופטימיזציה של גודל המטען הייעודי (payload)

מערכי הקואורדינטות הם גדולים, ולכן הכללת נתוני המסלול הנותרים בהודעות Pub/Sub יכולה להגדיל באופן משמעותי את גודל המטען הייעודי (עד 13-14KB לכל הודעה). אם אתם מקבלים עדכונים בתדירות גבוהה, הנפח הזה יכול להגדיל את עומס העיבוד בקצה העורפי ואת עלויות השימוש.

כדי לשפר את הסטרימינג, השתמשו בפרמטר pubsubFieldMask באובייקט TripConfig במהלך יצירת הנסיעה כדי להחריג שדות כבדים. לפרטים נוספים, קראו את המאמר הגדרות אופציונליות.

טיפול בסטייה מהמסלול (Waze בלבד)

הנהגים צריכים את גרסה 5.22 ומעלה של Waze.

אם הפעלתם דיווח על סטייה מהמסלול במהלך יצירת הנסיעה, כשהנהג סוטה מהמסלול, ה-API מחזיר מטא-נתונים של סטייה מהמסלול. אפשר לגשת לנתונים האלה בדרכים הבאות:

  • לפי דרישה: מפעילים את ה-method‏ GetTrip. השרת שומר את מצב החריגה האחרון שידוע.
  • בזמן אמת: נרשמים ל-Google Cloud Pub/Sub. השירות מפרסם עדכונים על חריגות באמצעות האירוע הקיים updated_trip תוך 5 שניות מרגע הזיהוי.

קריאת המטען הייעודי (payload) של החריגה

האובייקט last_route_deviation מספק את המטא-נתונים הבאים כדי לעזור לכם לנתח את האירוע.

שדה סוג תיאור
location LatLng הקואורדינטות של קווי הרוחב והאורך שבהן מכשיר הלקוח תיעד את החריגה.
source TriggerSource הסיבה לחריגה. אפשר להשתמש בזה כדי לקבוע אם הנהג ביצע פעולה לא צפויה או פעל לפי הנחיות המערכת:
  • ‫DRIVER_INITIATED_REROUTE: הנהג בחר באופן פעיל (לדוגמה, פנה לכיוון הלא נכון או בחר ידנית במסלול חדש).
  • ‫SYSTEM_INITIATED_REROUTE: אפליקציית הניווט חישבה מסלול חדש (לדוגמה, בגלל שינויים במצב התנועה או סגירת כבישים).
client_timestamp Timestamp השעה שבה מכשיר הלקוח זיהה את החריגה.
server_timestamp Timestamp השעה שבה השרת עיבד את עדכון החריגה.

טיפול במצבי סיום נסיעה

כשהנהג מגיע ליעד או מפסיק את הניווט, המטען הייעודי (payload) מחזיר את אחד ממצבי הסיום הבאים. אתם יכולים להשתמש בסטטוסים האלה כדי להפעיל את השלבים הבאים באפליקציה.

סטטוס תיאור הפעולה המומלצת
ARRIVED הנהג הגיע ליעד. בודקים את remainingDistanceMeters. אם הנהג חנה בקרבת מקום אבל לא בנקודת הציון המדויקת, כדאי לספק מסלול הליכה באפליקציה.
SUSPENDED הנהג יצא באופן ידני מהניווט המפורט לפני שהגיע ליעד.
מכיוון שמפות Google או Waze לא מחזירות את הנהגים באופן אוטומטי לאפליקציה שלכם כשהם יוצאים מסשן מוקדם, הנהג צריך ללחוץ ידנית על כפתור החזרה.
כדי לעזור לנהגים להשלים את הנסיעה, משווים בין execution.location לבין היעד. אם נשאר עוד מרחק, צריך לספק כפתור או קישור להמשך הנסיעה או למעבר למצב הליכה.
FAILED החיבור נקטע בגלל שגיאה טכנית. זה קורה אם האפליקציה לא יכולה לחשב מסלול או אם מופיעה אזהרת בטיחות. יכול להיות שהנהג עדיין מנווט, אבל לא יתקבלו עדכונים. חזרה למעקב ידני אחרי הסטטוס באפליקציה.
CLIENT_ERROR הסטטוס הזה מופיע בגלל אחת מהסיבות הבאות:
  • הנהג מבטל את ההסכמה.
  • הנהג משתמש בפלטפורמה שלא נתמכת, כמו Android Auto או Apple CarPlay.
  • האפליקציה שלכם עושה שימוש חוזר בטוקן של נסיעה בנסיעות נפרדות. לדוגמה, Navigation Connect דוחה בקשות לשינוי יעד הנסיעה או לעדכון נסיעה שהושלמה.
  • הנהג נמצא בארצות הברית בשלב כלשהו במהלך הנסיעה, אבל לא הפעלתם באפליקציה שיתוף נתונים בארצות הברית כשאימתתם את האפליקציה במהלך ההגדרה.
חזרה למעקב ידני אחרי הסטטוס באפליקציה.