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

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

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

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

מה תלמדו

כאן תלמדו איך:

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

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

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

מגבלות

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

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

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

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

נקודות קצה (endpoints)

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

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

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

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

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

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

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

מידות הרכב

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

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

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

לדוגמה:

  • רוחב: הרוחב של הרבה נגררים בארה"ב הוא 8 רגל ו-6 אינץ', שהם 2,590.8 מ"מ. עיגול כלפי מעלה ל-2,591 מ"מ יציין שהרכב גדול מ-8 רגל ו-6 אינץ', ולכן הוא יסווג כרכב גדול מדי בכבישים בארה"ב. כתוצאה מכך, המסלול יחושב לפי אילוצים שונים באופן משמעותי מהאילוצים המקוריים.
  • גובה: מסלול שעובר מתחת לגשר בגובה 3.3 מטרים לא מתאים למשאית עם נגרר בגובה 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 של בקשת ה-API של Routes, מסלולים שכוללים כבישי אגרה יסומנו בהתאם בשדה הזה.

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

כשמגדירים את 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

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

{
  "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 במקום ברמה הבסיסית (root) של הבקשה.

דוגמה לבקשה מסוג 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"
  },
  { ... }
]

השלבים הבאים