‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

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

מה תלמדו

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

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

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

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

מגבלות

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

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

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

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

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

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

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

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

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

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

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

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

מידות הרכב

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

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

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

לדוגמה:

רוחב: הרוחב של הרבה נגררים בארה"ב הוא 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 במסכת השדות של בקשת ה-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"
  },
  { ... }
]

השלבים הבאים

מסלול מפורט: איך משתמשים ב-routeToken ב-Navigation SDK ל-Android או ל-iOS.
אופטימיזציה ברמת צי הרכבים: משתמשים ב-Route Optimization API עם Large Vehicle Routing.
מאמרי העזרה של ה-API: רשימה מלאה של כל השדות והערכים האפשריים מופיעה במאמרי העזרה של Routes API.