חישוב מסלולים

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

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

אפשרויות לבקשות

אפשרות תיאור
origin, destination חובה. כל אחד מהם הוא ציון דרך: address (כתובת קריאה לאנשים או Plus Code),‏ place_id או lat_lng. אפשר לשלב פורמטים, למשל כתובת לנקודת המוצא ומזהה מקום ליעד.
travel_mode אמצעי התחבורה: DRIVE (ברירת מחדל), WALK, BICYCLE או TRANSIT. מסלולי WALK נמצאים בגרסת בטא, ולפעמים חסרים בהם מדרכות או שבילים להולכי רגל. חובה להציג את האזהרה הזו למשתמש בכל מסלולי ההליכה שמוצגים באפליקציה.
routing_preference איך נתוני התנועה משמשים לחישוב המסלול: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (ברירת המחדל) או ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, שהיא אפשרות Pro. אין תמיכה ב-ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL ב-WALK או ב-BICYCLE. מידע נוסף זמין במאמר מסלולים מבוססי-תנועה.
intermediate_waypoints תחנות מסודרות בין נקודת המוצא ליעד. המסלול עובר דרכן בסדר שצוין. בקשה יכולה לכלול עד 10 נקודות ציון ביניים, או 11 עד 25 כאפשרות Pro. אם תשלחו בקשה עם יותר מ-25, תקבלו את השגיאה INVALID_ARGUMENT. במסלולי תחבורה ציבורית אין תמיכה בנקודות ציון ביניים.
departure_time או arrival_time מתי לצאת מנקודת המוצא או להגיע ליעד, כחותמת זמן בפורמט RFC 3339. אפשר להגדיר רק אחד מהם. ברירת המחדל היא יציאה בזמן הנוכחי. בפרמטר TRANSIT, אפשר לציין זמן של עד 7 ימים בעבר או 100 ימים בעתיד. במצבי נסיעה אחרים, אי אפשר לבחור זמן בעבר, ואפשר לבחור זמן עד 365 ימים קדימה.
compute_alternative_routes כשהערך הוא true, התגובה כוללת מסלולים חלופיים בנוסף למסלול המומלץ, אם יש מסלולים חלופיים זמינים. ברירת המחדל היא false.
include_polyline כשהערך הוא true, כל מסלול בתגובה כולל את encodedPolyline. ברירת המחדל היא false.
location_bias קו רוחב וקו אורך שמשפיעים על האופן שבו נקודות הדרך בטקסט נפתרות, למשל כדי להבהיר כתובת.

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

שתי אפשרויות לבחירת המק"ט של Pro. בקשה שכוללת אחד מהם או את שניהם מחויבת לפי המק"ט של Pro:

אפשרות Pro מתי כדאי להשתמש בו
הכתובת ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL הוגדרה כמיקום הrouting_preference המשתמש שואל על התנועה, על עומס תנועה או על זמן הגעה שכולל את התנועה הנוכחית. מידע נוסף על ניתוב מבוסס-תנועה
‫11 עד 25 intermediate_waypoints המסלול צריך לכלול יותר מ-10 עצירות בין נקודת המוצא ליעד.

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

ניתוב בהתאם למצב התנועה

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

מגדירים את routing_preference לערך ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL כדי לחשב את המסלול ואת משך הזמן שלו בהתאם למצב התנועה הנוכחי, כשיש נתוני תנועה זמינים. אפשר להשתמש בה כשהמשתמש שואל כמה זמן נסיעה לוקחת כרגע. במסלולים של TRANSIT, ההגדרה הזו משתמשת בנתוני תחבורה ציבורית בזמן אמת, כמו עיכובים וביטולים, כשהם זמינים. הוא לא נתמך בנתיבים WALK או BICYCLE. בקשות כאלה מחזירות שגיאה מסוג INVALID_ARGUMENT. זו אפשרות ברמת Pro, ולכן הבקשה מחויבת במסגרת המק"ט של Pro. האפשרות הזו גם מוסיפה זמן אחזור.

במהלך הזמינות הכללית המוגבלת, אם הפרויקט לא נמצא ברשימת ההיתרים של Pro, האפשרות הזו נחשבת ל-ROUTING_PREFERENCE_TRAFFIC_UNAWARE. פרטים נוספים זמינים במאמר אפשרויות Pro במהלך זמינות מוגבלת (GA).

דוגמה

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

{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      "origin": {"address": "Ferry Building, San Francisco, CA"},
      "destination": {"address": "Golden Gate Park, San Francisco, CA"},
      "intermediate_waypoints": [
        {"address": "Palace of Fine Arts, San Francisco, CA"}
      ],
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_polyline": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

תשובה

התשובה מכילה routes[], בסדר יורד מהמומלץ ביותר להכי פחות מומלץ. מוחזר רק מסלול אחד, אלא אם הערך של compute_alternative_routes הוא true. כל מסלול כולל:

  • ‫distanceMeters: מרחק הנסיעה של המסלול, במטרים.
  • ‫duration: משך הזמן שנדרש כדי לעבור את המסלול. ב-ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, משך הזמן מביא בחשבון את מצב התנועה.
  • ‫encodedPolyline: הנתיב של המסלול כקו פוליגוני מקודד, כש-include_polyline הוא true. אתם יכולים להשתמש בו כדי לשרטט את המסלול במפה באמצעות ממשקי API אחרים של Google Maps Platform.
  • ‫attribution: השיוך שצריך להציג עם המסלול. דרישות ייחוס

אפשרויות ב-Pro במהלך הזמינות הכללית המוגבלת

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

  • ‫ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL מטופל כמו ROUTING_PREFERENCE_TRAFFIC_UNAWARE, והבקשה מחויבת לפי המק"ט של Essentials.
  • בקשה עם יותר מ-10 נקודות ציון ביניים מחזירה שגיאה מסוג INVALID_ARGUMENT ("יש תמיכה ב-10 נקודות ציון ביניים לכל היותר").

כדי לבקש גישה, קראו את המאמר אפשרויות Pro במהלך תקופת הזמינות הכללית המוגבלת.

חיוב ומכסות

כל בקשה של compute_routes היא אירוע אחד שניתן לחיוב:

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

המכסה של compute_routes היא 300 שאילתות לדקה לכל פרויקט, והיא משותפת לשני המק"טים. למידע על מחירים, ראו את טבלת התמחור הראשית ואת טבלת התמחור בהודו.

מגבלות

  • בקשה יכולה לכלול עד 25 נקודות ציון ביניים. 11 עד 25 היא אפשרות Pro. בקשה עם יותר מ-100,000 שורות תחזיר שגיאת INVALID_ARGUMENT.
  • במסלולי תחבורה ציבורית אין תמיכה בנקודות ציון ביניים. בקשה לתחבורה ציבורית עם נקודות ציון באמצע הדרך מחזירה שגיאת INVALID_ARGUMENT.
  • אי אפשר להשתמש בROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL במסלולי הליכה או רכיבה על אופניים.
  • במסלולים של תחבורה ציבורית, זמני היציאה וההגעה יכולים להיות עד 7 ימים בעבר או עד 100 ימים בעתיד. במצבי נסיעה אחרים, אי אפשר לבחור תאריך בעבר, ואפשר לבחור תאריך עד 365 ימים קדימה.
  • הקואורדינטות של נקודת הדרך צריכות להיות בטווחים הגיאוגרפיים החוקיים (קו רוחב בין ‎-90 ל-90, קו אורך בין ‎-180 ל-180).
  • הכלי לא מחזיר שלבים של מסלול מפורט, מקטעים או פרטים של קווי תחבורה ציבורית.