יצירת מסלולים וזמני הגעה משוערים לרכבים גדולים

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

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

במאמרי העזרה בנושא Route Optimization Truck Routing מוסבר איך לבצע חישובים ברמת צי הרכב עבור כלי רכב גדולים באמצעות Route Optimization API.

מה תלמדו

במאמר הזה נסביר איך:

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

דרישות מוקדמות

  1. צריך ליצור פרויקט בענן ב-Google Cloud ולהפעיל בו את Routes API.
  2. צריך להקצות לפרויקט את האפשרות 'ניתוב לרכבים גדולים'. ניתוב לרכבים גדולים זמין למספר מוגבל של לקוחות. כדי לבקש גישה, אפשר לפנות אלינו.

מגבלות

לפני שמתחילים, חשוב להכיר את המגבלות והדרישות הבאות.

  • זמינות גיאוגרפית: ניתוב של כלי רכב גדולים זמין ב-48 המדינות הרציפות בארצות הברית (זמינות כללית) וביפן (בשלב ניסיוני). השירות לא זמין באלסקה, בהוואי ובטריטוריות של ארה"ב.
  • המלצות לנהגים ובטיחות. הנהגים לא יכולים להסתמך רק על המסלולים שמוחזרים על ידי ה-API הזה כדי להבטיח בטיחות או חוקיות. אין ערובה לכך שהמסלולים מתאימים לרכב, ושימוש בהם עלול לחשוף את הנהגים לסכנות כמו גשרים נמוכים או כבישים שאסור לכלי רכב גדולים לנסוע בהם.
  • מסלולים במאמץ מרבי. במקרים מסוימים, ה-API לא יכול למצוא מסלול שעומד באופן מלא בהגבלות על נסיעות. במקום זאת, המערכת מחזירה מסלול 'במאמץ הכי טוב' שיכול להיות שהוא עדיין עובר באזורים מוגבלים. בתשובה של Routes API, המסלולים האלה מסומנים בבירור בשדה routeRestrictionsPartiallyIgnored. במקרים כאלה, מומלץ לתכנן את המסלול בקפידה, ועדיף להשתמש במקורות נתונים אחרים. אל תשתמשו במסלול שסומן כמקור מידע יחיד לתכנון או לניווט.
  • תכונות שלא נתמכות: התכונות הבאות לא נתמכות בניווט לרכבים גדולים:
    • מחירי אגרה למשאיות
    • מגבלות מהירות
    • ניתוב של חומרים מסוכנים רדיואקטיביים
  • מכסות שימוש: כל הבקשות כפופות למכסות הרגילות של שאילתות לשנייה (QPS).

יצירת בקשה למסלול משאיות

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

נקודות קצה

אפשר להשתמש בשתי נקודות קצה לניתוב משאיות:

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

פרמטרים מרכזיים של בקשות

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

  • ‫travelMode: מגדירים את הערך הזה ל-TRUCK.
  • ‫routingPreference: מגדירים את הערך הזה ל-TRAFFIC_AWARE_OPTIMAL.
  • ‫routeModifiers: האובייקט הזה מכיל את האובייקט vehicleInfo שבו מגדירים את מאפייני הרכב. האובייקט vehicleInfo מתואר בפירוט בהמשך.

ציון מאפייני הרכב

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

מידות הרכב

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

המרת יחידות אימפריאליות ליחידות מטריות

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

לדוגמה:

  • רוחב: לנגררים רבים בארה"ב יש רוחב של 8' 6", ששווה ל-2,590.8 מ"מ. עיגול כלפי מעלה ל-2,591 מ"מ יצביע על כך שהרכב גדול מ-8' 6", ולכן הוא יסווג כרכב גדול מדי בכבישים בארה"ב. התוצאה תהיה מסלול שחושב לפי אילוצים שונים באופן משמעותי מאלה שהתכוונתם אליהם.
  • גובה: מסלול שעובר מתחת לגשר בגובה 3.35 מ' לא יתאים למשאית עם נגרר בגובה 4.1 מ'. עם זאת, משאיות קטנות יותר, באורך של כ-3 מטרים, יוכלו לעבור במעבר התת-קרקעי. לכן, חשוב מאוד לציין את מאפייני הרכב בצורה מדויקת.

דיאגרמה שממחישה את המידות של משאית ביחס למידות של מעבר תת-קרקעי

בקטע הקוד הבא מוצג אובייקט vehicleInfo לדוגמה:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

vehicleInfo שדות אובייקט

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

שדה תיאור הערות / ערכים
totalHeightMm הגובה המקסימלי של הרכב. במילימטרים, מעוגל כלפי מטה. פרטים נוספים על עיגול זמינים במאמר בנושא המרת יחידות אימפריאליות ליחידות מטריות.
totalWidthMm הרוחב המקסימלי של הרכב. במילימטרים, מעוגל כלפי מטה.
totalLengthMm האורך המשולב הכולל של כלי הרכב וכל הנגררים. במילימטרים, מעוגל כלפי מטה.
totalWeightKg המשקל הכולל של הרכב (כולל נגררים ומטען). בקילוגרמים, מעוגל כלפי מטה.
totalAxleCount המספר הכולל של הסרנים ברכב ובכל הנגררים. מדויקת.
‫trailerInfo (אופציונלי) מערך של אובייקטים, אחד לכל טריילר. לא מציינים את התג הזה אם מדובר ברכב ללא נגררים, כמו משאית סגורה.
‫hazardousGoodsTypes (אופציונלי) מערך שמציין חומרים מסוכנים שנמצאים על הסיפון. EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

שימוש במסכות שדות

כדי לקבל את התוצאות הטובות ביותר, כדאי לכלול את הכותרת X-Goog-FieldMask בבקשה כדי לציין בדיוק את השדות שרוצים בתגובה. מסכות שדות מפחיתות את זמן האחזור ומבטיחות שתקבלו שדות חשובים של ייעוץ. לפחות, תמיד צריך לכלול את routes.travelAdvisory.routeRestrictionsPartiallyIgnored במסכת השדות, כי הוא מציין אם במסלול יש מגבלה אחת או יותר שחלות על הרכב שלכם.

מידע נוסף על FieldMasks עם Routes API זמין במאמר הזה.

כבישי אגרה

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

ציון של avoidTolls לא מבטיח שנתיבים ללא תשלום יופיעו בתגובה. במקרים מסוימים, צריך לנסוע בכביש אגרה כדי להגיע מהמוצא ליעד. אם כוללים את routes.warnings ב-fieldmask של בקשת Routes API, מסלולים שמכילים כבישי אגרה יסומנו בהתאם בשדה הזה.

התנהגויות אחרות של ניתוב

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

חישוב מסלול יחיד באמצעות computeRoutes

משתמשים בנקודת הקצה computeRoutes כדי לחשב מסלול ספציפי למשאית בין נקודת מוצא אחת ליעד אחד.

דוגמה לבקשת computeRoutes

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

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

דוגמה לתגובה computeRoutes

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

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

פרשנות של התשובה computeRoutes

בקשה מוצלחת לנקודת הקצה computeRoutes מחזירה אובייקט JSON של תשובה שמכיל מסלול אפשרי אחד או יותר.

שדות התשובה העיקריים
  • גיאומטריית מסלול מקודדת: routes.polyline. אפשר להשתמש בנתונים האלה כדי לרנדר את המסלול במפה.
  • משך הנסיעה המשוער: routes.duration (בשניות). משך הנסיעה בניתוב לרכבים גדולים מחושב באמצעות מודל חדש שאומן על מהירויות נסיעה שנמדדו בפועל של משאיות ברשת הכבישים. אפשר להשתמש בו גם כדי לחשב את זמן ההגעה המשוער על ידי הוספת משך הנסיעה המשוער לשעת ההמראה הצפויה.
  • המרחק הכולל של המסלול: routes.distanceMeters (במטרים).
  • אסימון מסלול: routes.routeToken. זהו אסימון אטום שמייצג את המסלול המחושב המדויק. מעבירים את הטוקן הזה ל-Navigation SDK כדי לוודא שהנהג יראה את אותו מסלול ספציפי למשאית. לפרטים נוספים, אפשר לעיין במדריכי Navigation SDK ל-Android או ל-iOS.
בדיקה לאיתור סימון של מסלולים לא בטוחים

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

השדה הזה משמש כדגל כדי לענות על השאלה: "האם המסלול הזה מסומן כבעיה פוטנציאלית?"

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

חישוב מטריצה של מסלולים (computeRouteMatrix)

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

כדי להשתמש ב-computeRouteMatrix, צריך לציין את vehicleInfo בכל אובייקט origin ולא בשורש הבקשה.

דוגמה לבקשת computeRouteMatrix

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

דוגמה לתגובה computeRouteMatrix

התגובה היא מערך שבו כל אובייקט מכיל את משך הזמן ואת distanceMeters של זוג אחד של נקודת מוצא ויעד.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

השלבים הבאים