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

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

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

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

מה תלמדו

במדריך הזה תלמדו איך:

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

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

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

מגבלות

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

  • זמינות גיאוגרפית: ניתוב של כלי רכב גדולים זמין רק ב-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", ולכן הוא יסווג כרכב גדול מדי בכבישים בארה"ב. התוצאה תהיה מסלול שחושב לפי אילוצים שונים באופן משמעותי מאלה שהתכוונתם אליהם.
  • גובה: מסלול שעובר מתחת לגשר בגובה 11' לא יתאים למשאית עם נגרר טיפוסית בגובה 13.5'. עם זאת, משאיות קטנות יותר, באורך של כ-10 רגל, יוכלו לעבור במעבר התת-קרקעי. לכן, חשוב מאוד לציין את מאפייני הרכב בצורה מדויקת.

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

בקטע הקוד הבא מוצג אובייקט 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, מסלולים שמכילים כבישי אגרה יסומנו בהתאם בשדה הזה.

דוגמה מלאה לבקשת curl

זוהי בקשת 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

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

שדות תשובה עיקריים

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

בדיקה לאיתור סימון של מסלולים לא בטוחים

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

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

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

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

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

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

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

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

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

בקשה לדוגמה

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

דוגמה לתשובה

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

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

השלבים הבאים