קבלת מסלול דרך Directions API (קודם)

מפתחים באזור הכלכלי האירופי (EEA)

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

כדי לחשב מסלולים בתגובה לפעולות של המשתמשים בזמן אמת (לדוגמה, בתוך רכיב בממשק המשתמש), אתם יכולים להשתמש ב-Directions API (דור קודם) או בשירות המסלולים אם אתם משתמשים ב-Maps JavaScript API. לשימוש בצד השרת, אתם יכולים להשתמש ב-Java Client, ‏ Python Client,‏ Go Client ו-Node.js Client לשירותי מפות Google.

באמצעות Directions API (דור קודם), אתם יכולים:

  • לחפש מסלולים לכמה אמצעי תחבורה, כולל תחבורה ציבורית, נהיגה, הליכה או רכיבה על אופניים.
  • החזרת מסלול עם כמה חלקים באמצעות סדרה של נקודות ציון.
  • מציינים את נקודות המוצא, היעדים ונקודות הדרך כמחרוזות טקסט (למשל, "Chicago, IL" או "Darwin, NT, Australia"), כמזהי מקומות או כקואורדינטות של קו רוחב/קו אורך.

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

לפני שמתחילים

לפני שמתחילים להשתמש ב-Directions API (הדור הקודם), צריך פרויקט עם חשבון לחיוב ו-Directions API (הדור הקודם) מופעל. מידע נוסף זמין במאמר הגדרה במסוף Cloud.

יצירת בקשות ל-Directions API (דור קודם)

בקשה ל-Directions API (הגרסה הקודמת) נראית כך:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

כאשר outputFormat יכול להיות אחד מהערכים הבאים:

  • ‫json (מומלץ) מציין פלט ב-JavaScript Object Notation ‏(JSON)
  • ‫xml מציין פלט בפורמט XML

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

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

פרמטרים נדרשים

destination

מזהה המקום, הכתובת או הערך הטקסטואלי של קו הרוחב/קו האורך שאליו רוצים לחשב מסלול. האפשרויות של הפרמטר destination זהות לאלה של הפרמטר origin.

origin

מזהה המקום, הכתובת או הערך הטקסטואלי של קו הרוחב/קו האורך שמהם רוצים לחשב את המסלול.

  • מזהי מקומות צריכים להתחיל ב-place_id:. אפשר לאחזר מזהי מקומות מ-Geocoding API ומ-Places API (כולל השלמה אוטומטית למקומות). דוגמה לשימוש במזהי מקומות מהשלמה אוטומטית למקומות מופיעה במאמר השלמה אוטומטית למקומות וקבלת מסלול. מידע נוסף על מזהי מקומות זמין בסקירה הכללית על מזהי מקומות.

    origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
    
  • אם מעבירים כתובת, שירות המסלולים ממיר את המחרוזת לקואורדינטות של קווי אורך ורוחב כדי לחשב את המסלול. הקואורדינטה הזו עשויה להיות שונה מזו שמוחזרת על ידי Geocoding API, למשל כניסה לבניין ולא מרכז הבניין.

    origin=24+Sussex+Drive+Ottawa+ON
    

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

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

    origin=41.43206,-81.38992
    
  • הפורמט של Plus Codes צריך להיות קוד גלובלי או קוד משולב. צריך להזין את ה-Plus Codes בפורמט שמוצג כאן (סימני פלוס מומרים לתווי בריחה (escape) של כתובת URL %2B ורווחים מומרים לתווי בריחה (escape) של כתובת URL %20).

    • קוד גלובלי הוא קוד אזור בן 4 תווים וקוד מקומי בן 6 תווים או יותר (849VCWC8+R9 הוא 849VCWC8%2BR9).
    • קוד מורכב הוא קוד מקומי באורך 6 תווים או יותר עם מיקום מפורש (CWC8+R9 Mountain View, CA, USA הוא CWC8%2BR9%20Mountain%20View%20CA%20USA).
הערה: כדי לשפר את היעילות והדיוק, מומלץ להשתמש במזהי מקומות כשאפשר. המזהים האלה מפורשים באופן ייחודי, כמו זוג ערכים של קו רוחב/קו אורך, ומספקים יתרונות של המרת כתובות לקואורדינטות (geocoding) לצורך ניתוב, כמו נקודות גישה ומשתני תנועה. בניגוד לכתובת, מזהים לא דורשים מהשירות לבצע חיפוש או בקשת ביניים לקבלת פרטי מקום, ולכן הביצועים טובים יותר.

פרמטרים אופציונליים

חלופות

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

arrival_time

מציין את זמן ההגעה המועדף למסלול לתחבורה ציבורית, בשניות מאז חצות, 1 בינואר 1970 UTC. אפשר לציין את departure_time או את arrival_time, אבל לא את שניהם. שימו לב שצריך לציין את arrival_time כמספר שלם.

הימנעות

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

  • tolls מציין שהמסלול המחושב צריך להימנע מכבישי אגרה או מגשרים.
  • highways מציין שהמסלול המחושב צריך להימנע מכבישים מהירים.
  • ‫ferries מציין שהמסלול המחושב צריך להימנע ממעבורות.
  • indoor מציין שהמסלול המחושב צריך להימנע ממדרגות פנימיות במסלולי הליכה ומסלול לתחבורה ציבורית.

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

avoid=tolls|highways|ferries.

departure_time

מציין את שעת היציאה המועדפת. אפשר לציין את השעה כמספר שלם בשניות מאז חצות, 1 בינואר 1970, לפי שעון UTC. אם מציינים ערך של departure_time שמאוחר יותר מ-9999-12-31T23:59:59.999999999Z, ה-API יחזיר את הערך של departure_time ל-9999-12-31T23:59:59.999999999Z. אפשר גם לציין את הערך now, שמגדיר את שעת היציאה לשעה הנוכחית (עד לרמת דיוק של שנייה). אפשר לציין את שעת היציאה בשני מקרים:

  • בבקשות שבהן אמצעי התחבורה הוא תחבורה ציבורית: אפשר לציין את departure_time או את arrival_time. אם לא מציינים אף אחת מהשעות, הערך של departure_time מוגדר כברירת מחדל לשעה הנוכחית (כלומר, שעת היציאה מוגדרת כברירת מחדל לשעה הנוכחית).
  • בבקשות שבהן אמצעי ההגעה הוא נהיגה: אפשר לציין את הפרמטר departure_time כדי לקבל מסלול ומשך נסיעה (שדה התגובה: duration_in_traffic) שמביאים בחשבון את מצב התנועה. הערך של departure_time צריך להיות השעה הנוכחית או שעה בעתיד. התאריך לא יכול להיות בעבר.
הערה: אם לא מציינים את שעת היציאה, בחירת המסלול ומשך הנסיעה מבוססים על רשת הכבישים ועל מצב התנועה הממוצע ללא תלות בזמן. התוצאות של בקשה מסוימת עשויות להשתנות לאורך זמן בגלל שינויים ברשת הכבישים, עדכונים במצב התנועה הממוצע והאופי המבוזר של השירות. התוצאות עשויות להשתנות גם בין מסלולים כמעט זהים בכל זמן או תדירות.
הערה: בקשות של מטריצת מרחקים שמציינות את departure_time כש-mode=driving מוגבלות ל-100 רכיבים לכל היותר לכל בקשה. מספר הרכיבים מוגדר לפי מספר נקודות המוצא כפול מספר היעדים.

language

השפה שבה התוצאות יוחזרו. חשוב לזכור שהשפה משפיעה רק על הכתובות שעברו המרה לקואורדינטות בשדות start_address ו-end_address, על הטקסט המותאם לשוק המקומי בשדות distance ו-duration (בקטעי המסלול ובשלבים) ועל תיאור התמרונים בשדה html_instructions, אבל לא על השמות והכתובות בשדה html_instructions, שמוצגים בשפה ובכתב המקומיים.

  • כאן אפשר לעיין ברשימת השפות הנתמכות. ‫Google מעדכנת לעיתים קרובות את השפות הנתמכות, ולכן יכול להיות שהרשימה הזו לא מלאה.
  • אם לא מציינים את הפרמטר language, ה-API מנסה להשתמש בשפה המועדפת שצוינה בכותרת Accept-Language.
  • ה-API מנסה לספק כתובת רחוב שקריאה גם למשתמש וגם למקומיים. כדי להשיג את המטרה הזו, הוא מחזיר כתובות רחוב בשפה המקומית, בתעתיק לכתב שהמשתמש יכול לקרוא במידת הצורך, תוך התחשבות בשפה המועדפת. כל שאר הכתובות מוחזרות בשפה המועדפת. כל רכיבי הכתובת מוחזרים באותה שפה, שנבחרת מהרכיב הראשון.
  • אם השם לא זמין בשפה המועדפת, ה-API משתמש בהתאמה הקרובה ביותר.
  • השפה המועדפת משפיעה קצת על קבוצת התוצאות שה-API בוחר להחזיר, ועל הסדר שבו הן מוחזרות. הכלי להמרת כתובות לקואורדינטות מפרש קיצורים בצורה שונה בהתאם לשפה, כמו קיצורים של סוגי רחובות או מילים נרדפות שעשויות להיות תקפות בשפה אחת אבל לא בשפה אחרת. לדוגמה, utca ו-tér הן מילים נרדפות לרחוב בהונגרית.

מצב

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

  • ‫driving (ברירת המחדל) מציין מסלול נסיעה רגיל או מרחק באמצעות רשת הכבישים.
  • ‫walking מבקש מסלול הליכה או מרחק דרך שבילים להולכי רגל ומדרכות (אם יש כאלה).
  • ‫bicycling מבקש מסלול רכיבה על אופניים או מרחק דרך שבילי אופניים ורחובות מועדפים (אם יש כאלה).
  • ‫transit מבקש מסלולים או מרחק באמצעות מסלולי תחבורה ציבורית (אם יש כאלה). אם מגדירים את המצב ל-transit, אפשר לציין גם departure_time או arrival_time. אם לא מציינים אף אחת מהשעות, הערך של departure_time מוגדר כברירת מחדל לשעה הנוכחית (כלומר, שעת היציאה מוגדרת כברירת מחדל לשעה הנוכחית). אפשר גם לכלול transit_mode או transit_routing_preference. אפשר לחפש נסיעות בתחבורה ציבורית עד 7 ימים בעבר או עד 100 ימים בעתיד, בכפוף לזמינות של מידע על תחבורה ציבורית שמסופק על ידי ספקי נתונים. לוחות הזמנים של התחבורה הציבורית משתנים לעיתים קרובות, והנסיעות הזמינות בתחבורה הציבורית עשויות להשתנות עם הזמן. אין ערובה לכך שהתחזיות לטווח הרחוק יהיו עקביות.
הערה: לפעמים מסלולי הליכה ורכיבה על אופניים לא כוללים שבילים ברורים להולכי רגל או לרוכבי אופניים, ולכן המסלולים האלה יחזירו אזהרות בתוצאה שמוחזרת, שצריך להציג למשתמש.

אזור

קוד האזור, שמוגדר כערך ccTLD (דומיין ברמה העליונה) באורך שני תווים. רוב קודי ה-ccTLD זהים לקודי ISO 3166-1, עם כמה חריגים בולטים. לדוגמה, סיומת ה-ccTLD של בריטניה היא uk‏ (‎.co.uk), וקוד ה-ISO 3166-1 שלה הוא gb (מבחינה טכנית, עבור הישות "הממלכה המאוחדת של בריטניה הגדולה וצפון אירלנד").

traffic_model

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

  • best_guess (ברירת המחדל) מציין שהערך המוחזר של duration_in_traffic צריך להיות האומדן הטוב ביותר של זמן ההגעה, בהתאם למידע הידוע על מצב התנועה ההיסטורי ועל מצב התנועה בזמן אמת. ככל ש-departure_time קרוב יותר לזמן הנוכחי, כך החשיבות של עדכוני התנועה בזמן אמת גדלה.
  • pessimistic מציין שהערך duration_in_traffic שמוחזר אמור להיות ארוך יותר מזמן ההגעה בפועל ברוב הימים, אבל יכול להיות שבימים מסוימים עם מצב תנועה גרוע במיוחד, זמן ההגעה בפועל יהיה ארוך יותר מהערך הזה.
  • optimistic מציין שהערך duration_in_traffic שמוחזר אמור להיות קצר יותר מזמן ההגעה בפועל ברוב הימים, אבל יכול להיות שבימים מסוימים מצב התנועה יהיה טוב במיוחד והנסיעה תהיה מהירה יותר מהערך הזה.

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

transit_mode

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

  • ‫bus מציין שהמסלול המחושב צריך להעדיף נסיעה באוטובוס.
  • subway מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת תחתית.
  • train מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת.
  • ‫tram מציין שהמסלול המחושב צריך להעדיף נסיעה בחשמלית וברכבת קלה.
  • ‫rail מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת, בחשמלית, ברכבת קלה וברכבת תחתית. זה שווה ערך ל-transit_mode=train|tram|subway.

transit_routing_preference

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

  • ‫less_walking מציין שהמסלול המחושב צריך להעדיף הליכה מוגבלת.
  • fewer_transfers מציין שהמסלול המחושב צריך להעדיף מספר מוגבל של החלפות.

יחידות

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

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

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

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

נקודות ציון

זהירות: בקשות שכוללות יותר מ-10 נקודות ציון (בין 11 ל-25) או אופטימיזציה של נקודות ציון מחויבות בתעריף גבוה יותר. מידע נוסף על חיוב במוצרים של Google Maps Platform.

מציין מערך של מיקומים שצריך לכלול לאורך המסלול בין נקודת המוצא לנקודת היעד, כמיקומים למעבר או לעצירה. נקודות הדרך משנות את המסלול על ידי הפנייתו דרך המיקומים שצוינו. ה-API תומך בנקודות ציון לאמצעי ההגעה הבאים: נהיגה, הליכה ורכיבה על אופניים, אבל לא לתחבורה ציבורית. אפשר לציין מיקום אחד או יותר, מופרדים באמצעות התו "קו אנכי" (| או %7C), בפורמט של מזהה מקום, כתובת או קואורדינטות של קו רוחב/קו אורך. כברירת מחדל, שירות המסלולים מחשב מסלול באמצעות נקודות הדרך בסדר שבו הן ניתנות. סדר העדיפויות לניתוח הערך של נקודת הדרך הוא מזהה המקום, קואורדינטות של קו רוחב/קו אורך, ואז הכתובת.

  • אם מעבירים מזהה מקום, צריך להוסיף לו את הקידומת place_id:. אפשר לאחזר מזהי מקומות מ-Geocoding API ומ-Places API (כולל השלמה אוטומטית למקומות). דוגמה לשימוש במזהי מקומות מהשלמה אוטומטית למקומות מופיעה במאמר השלמה אוטומטית למקומות וקבלת מסלול. מידע נוסף על מזהי מקומות זמין בסקירה הכללית על מזהי מקומות.
    כדי לשפר את היעילות והדיוק, מומלץ להשתמש במזהי מקומות כשאפשר. המזהים האלה מפורשים באופן ייחודי, כמו זוג ערכים של קו רוחב/קו אורך, ומספקים יתרונות של המרת כתובות לקואורדינטות לצורך ניתוב, כמו נקודות גישה ומשתני תנועה. בניגוד לכתובת, מזהים לא דורשים מהשירות לבצע חיפוש או בקשת ביניים לקבלת פרטי מקום, ולכן הביצועים טובים יותר.
  • אם מעבירים קואורדינטות של קו רוחב/אורך, הערכים עוברים ישירות לשרת הקצה הקדמי כדי לחשב מסלולים בלי המרת כתובות לקואורדינטות (geocoding). הנקודות מוצמדות לכבישים, ויכול להיות שהן לא יספקו את הדיוק שהאפליקציה שלכם צריכה. השתמשו בקואורדינטות כשאתם בטוחים שהערכים באמת מציינים את הנקודות שהאפליקציה צריכה בשביל הניתוב, בלי קשר לנקודות גישה אפשריות או לפרטים נוספים של המרת כתובות לקואורדינטות. חשוב לוודא שפסיק (%2C) ולא רווח (%20) מפריד בין ערכי קו הרוחב וקו האורך.
  • אם מעבירים כתובת, שירות המסלולים ימיר את המחרוזת לקואורדינטות של קווי אורך ורוחב כדי לחשב את המסלול. אם ערך הכתובת לא חד-משמעי, יכול להיות שהערך יגרום לחיפוש כדי להבדיל בין כתובות דומות. לדוגמה, "רחוב הרצל" יכול להיות ערך מלא או ערך חלקי של "רחוב הרצל 1" או "רחוב הרצל 2". התוצאה הזו עשויה להיות שונה מהתוצאה שמוחזרת על ידי Geocoding API. כדי למנוע פרשנויות שגויות, אפשר להשתמש במזהי מקומות.
  • לחלופין, אפשר לספק קבוצה מקודדת של נקודות באמצעות אלגוריתם של קו פוליגוני מקודד. קבוצה מקודדת שימושית למספר גדול של נקודות ציון, כי כתובת ה-URL קצרה משמעותית. בכל שירותי האינטרנט, יש מגבלה של 16,384 תווים לכתובת URL.
    • לפני קווים פוליגוניים מקודדים צריך להוסיף את הקידומת enc: ואחריה נקודתיים (:). לדוגמה: waypoints=enc:gfo}EtohhU:.
    • אפשר גם לכלול כמה קווים פוליגוניים מקודדים, שמופרדים באמצעות התו |. לדוגמה, waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:

השפעה על מסלולים באמצעות נקודות עצירה ונקודות מעבר

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

אם רוצים להשפיע על המסלול באמצעות נקודות ציון בלי להוסיף עצירת ביניים, מוסיפים את הקידומת via: לנקודת הציון. נקודות ציון עם הקידומת via: לא יוסיפו רשומה למערך legs, אבל המסלול יעבור דרך נקודת הציון.

כתובת ה-URL הבאה משנה את הבקשה הקודמת כך שהמסלול עובר דרך לקסינגטון בלי לעצור:

https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

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

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

אופטימיזציה של נקודות הציון

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

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

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

https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

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

"waypoint_order": [ 3, 2, 0, 1 ]
זהירות: בקשות שכוללות אופטימיזציה של נקודות ציון מחויבות בתעריף גבוה יותר. מידע נוסף על החיוב במוצרים של Google Maps Platform

המאמרים הבאים

דוגמאות להוראות הגעה

תשובות לגבי מסלולים