Directions Service (Legacy)

מפתחים באזור הכלכלי האירופי (EEA)
הערה: ספריות בצד השרת

סקירה כללית

אפשר לחשב מסלולים (באמצעות מגוון אמצעי תחבורה) באמצעות האובייקט DirectionsService. האובייקט הזה מתקשר עם שירות המסלולים של Google Maps API, שמקבל בקשות למסלולים ומחזיר מסלול יעיל. זמן ההגעה הוא הגורם העיקרי שעובר אופטימיזציה, אבל יכול להיות שגורמים אחרים, כמו מרחק, מספר הפניות ועוד, יילקחו בחשבון. אתם יכולים לטפל בתוצאות המסלולים בעצמכם או להשתמש באובייקט DirectionsRenderer כדי לעבד את התוצאות האלה.

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

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

תחילת העבודה

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

כדי לראות את רשימת ממשקי ה-API שמופעלים:

  1. נכנסים ל מסוף Google Cloud.
  2. לוחצים על הכפתור Select a project, בוחרים את הפרויקט שהגדרתם ל-Maps JavaScript API ולוחצים על Open.
  3. ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Directions API (Legacy)‎.
  4. אם ה-API מופיע ברשימה, אתם מוכנים. אם ה-API לא מופיע ברשימה, מפעילים אותו בכתובת https://console.cloud.google.com/apis/library/directions-backend.googleapis.com

תמחור ומדיניות

תמחור

כדי לקבל מידע על מדיניות התמחור והשימוש בשירות Directions ב-JavaScript, קראו את המאמר שימוש וחיוב ב-Directions API (הדור הקודם).

מדיניות

השימוש בשירות Directions חייב להיות בהתאם למדיניות שמתוארת בנושא Directions API (דור קודם).

בקשות לקבלת מסלול

הגישה לשירות המסלולים היא אסינכרונית, כי Google Maps API צריך לבצע קריאה לשרת חיצוני. לכן צריך להעביר שיטת קריאה חוזרת (callback) שתתבצע בסיום הבקשה. שיטת הקריאה החוזרת הזו אמורה לעבד את התוצאות. חשוב לזכור ששירות המסלולים עשוי להחזיר יותר ממסלול נסיעה אפשרי אחד כמערך של routes[] נפרדים.

כדי להשתמש במסלולים ב-Maps JavaScript API, יוצרים אובייקט מסוג DirectionsService וקוראים ל-DirectionsService.route() כדי לשלוח בקשה לשירות המסלולים. מעבירים לו ליטרל של אובייקט DirectionsRequest שמכיל את מונחי הקלט ושיטת קריאה חוזרת להפעלה אחרי קבלת התגובה.

הליטרל של האובייקט DirectionsRequest מכיל את השדות הבאים:

{
  origin: LatLng | String | google.maps.Place,
  destination: LatLng | String | google.maps.Place,
  travelMode: TravelMode,
  transitOptions: TransitOptions,
  drivingOptions: DrivingOptions,
  unitSystem: UnitSystem,
  waypoints[]: DirectionsWaypoint,
  optimizeWaypoints: Boolean,
  provideRouteAlternatives: Boolean,
  avoidFerries: Boolean,
  avoidHighways: Boolean,
  avoidTolls: Boolean,
  region: String
}

השדות האלה מוסברים בהמשך:

  • ‫origin (חובה) מציין את מיקום ההתחלה שממנו יחושבו המסלולים. אפשר לציין את הערך הזה בתור String (לדוגמה, "Chicago, IL"), בתור ערך LatLng או בתור אובייקט Place. אם משתמשים באובייקט Place, אפשר לציין מזהה מקום, מחרוזת שאילתה או מיקום LatLng. אפשר לאחזר מזהי מקומות מהשירותים Geocoding,‏ חיפוש מקומות ו-השלמה אוטומטית למקומות ב-Maps JavaScript API. דוגמה לשימוש במזהי מקומות מהשלמה אוטומטית למקומות מופיעה במאמר השלמה אוטומטית למקומות וקבלת מסלול.
  • ‫destination (חובה) מציין את מיקום הסיום שלגביו רוצים לחשב מסלול. האפשרויות זהות לאלה של השדה origin שמתואר למעלה.
  • ‫travelMode (חובה) מציין את אמצעי התחבורה שבו צריך להשתמש כשמחשבים מסלול. הערכים התקינים מפורטים בקטע אמצעי תחבורה בהמשך.
  • ‫transitOptions (אופציונלי) מציין ערכים שחלים רק על בקשות שבהן travelMode הוא TRANSIT. הערכים החוקיים מתוארים בקטע אפשרויות הובלה שבהמשך.
  • ‫drivingOptions (אופציונלי) מציין ערכים שחלים רק על בקשות שבהן travelMode הוא DRIVING. הערכים החוקיים מתוארים בקטע אפשרויות נהיגה שבהמשך.

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

  • ‫waypoints[] (אופציונלי) מציין מערך של DirectionsWaypoint. נקודות הדרך משנות את המסלול על ידי ניתוב דרך המיקומים שצוינו. נקודת ציון מוגדרת כליטרל של אובייקט עם השדות שמוצגים בהמשך:

    • ‫location מציין את המיקום של נקודת הדרך, בתור LatLng, בתור אובייקט Place או בתור String שיעבור המרה לקואורדינטות.
    • stopover הוא ערך בוליאני שמציין שנקודת הדרך היא עצירה במסלול, וכתוצאה מכך המסלול מתפצל לשני מסלולים.

    (מידע נוסף על נקודות דרך מופיע בקטע שימוש בנקודות דרך במסלולים בהמשך).

  • optimizeWaypoints (אופציונלי) מציין שאפשר לשפר את המסלול באמצעות waypoints שסופק על ידי סידור מחדש של נקודות הדרך בסדר יעיל יותר. אם true, שירות המסלולים יחזיר את waypoints שסודרו מחדש בשדה waypoint_order.(מידע נוסף זמין בקטע שימוש בנקודות ציון במסלולים בהמשך).
  • provideRouteAlternatives (אופציונלי) כשהערך מוגדר כ-true, מציין ששירות המסלולים יכול לספק יותר ממסלול חלופי אחד בתגובה. חשוב לזכור שאם מבקשים מסלולים חלופיים, יכול להיות שזמן התגובה מהשרת יהיה ארוך יותר. האפשרות הזו זמינה רק לבקשות בלי נקודות ביניים.
  • avoidFerries (אופציונלי) כשהערך הוא true, המשמעות היא שהמסלולים המחושבים צריכים להימנע ממעבורות, אם אפשר.
  • avoidHighways (אופציונלי) כשהערך הוא true, המערכת תנסה להימנע מכבישים מהירים במסלולים שהיא מחשבת.
  • avoidTolls (אופציונלי) כשהערך הוא true, המערכת תנסה להימנע מכבישי אגרה במסלולים שהיא מחשבת.
  • ‫region (אופציונלי) מציין את קוד האזור, שמוגדר כערך ccTLD (דומיין ברמה העליונה) באורך שני תווים. (למידע נוסף, עיינו בקטע הטיה לפי אזור בהמשך).

הנה דוגמה ל-DirectionsRequest:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

אמצעי הגעה

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

  • DRIVING (ברירת מחדל) מציין מסלול נסיעה רגיל באמצעות רשת הכבישים.
  • ‫BICYCLING מבקש מסלול רכיבה על אופניים דרך שבילי אופניים ורחובות מועדפים.
  • TRANSIT מבקש מסלולים בתחבורה ציבורית.
  • ‫WALKING מבקש מסלול הליכה דרך שבילים להולכי רגל ומדרכות.

כדי לבדוק באיזו מידה יש תמיכה במסלולים במדינה מסוימת, אפשר לעיין בפרטי הכיסוי של Google Maps Platform. אם מבקשים מסלול לאזור שבו סוג המסלול הזה לא זמין, התשובה תהיה DirectionsStatus="ZERO_RESULTS".

הערה: יכול להיות שמסלולי הליכה לא יכללו שבילים ברורים להולכי רגל, ולכן מסלולי הליכה יחזירו אזהרות ב-DirectionsResult. תמיד צריך להציג את האזהרות האלה למשתמש. אם לא משתמשים ב-DirectionsRenderer שמוגדר כברירת מחדל, צריך לוודא שהאזהרות מוצגות.

אפשרויות תחבורה ציבורית

האפשרויות הזמינות לבקשת מסלול משתנות בהתאם לאמצעי התחבורה. כשמבקשים מסלול לתחבורה ציבורית, המערכת מתעלמת מהאפשרויות avoidHighways, avoidTolls, waypoints[] ו-optimizeWaypoints. אפשר לציין אפשרויות מסלול ספציפיות לתחבורה ציבורית באמצעות הליטרל של האובייקט TransitOptions.

מסלולים לתחבורה ציבורית תלויים בזמן. המסלולים יוחזרו רק לזמנים עתידיים.

הליטרל של האובייקט TransitOptions מכיל את השדות הבאים:

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

השדות האלה מוסברים בהמשך:

  • arrivalTime (אופציונלי) מציין את זמן ההגעה הרצוי כאובייקט Date. אם מציינים את זמן ההגעה, המערכת מתעלמת מזמן היציאה.
  • ‫departureTime (אופציונלי) מציין את זמן היציאה הרצוי כאובייקט Date. המערכת תתעלם מהערך של departureTime אם צוין הערך של arrivalTime. אם לא מציינים ערך ל-departureTime או ל-arrivalTime, ברירת המחדל היא הזמן הנוכחי.
  • ‫modes[] (אופציונלי) הוא מערך שמכיל ליטרל אחד או יותר של אובייקט TransitMode. אפשר לכלול את השדה הזה רק אם הבקשה כוללת מפתח API. כל TransitMode מציין אמצעי תחבורה מועדף. אלה הערכים המותרים:
    • ‫BUS מציין שהמסלול המחושב צריך להעדיף נסיעה באוטובוס.
    • ‫RAIL מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת, בחשמלית, ברכבת קלה וברכבת תחתית.
    • SUBWAY מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת תחתית.
    • TRAIN מציין שהמסלול המחושב צריך להעדיף נסיעה ברכבת.
    • TRAM מציין שהמסלול המחושב צריך להעדיף נסיעה בחשמלית וברכבת קלה.
  • ‫routingPreference (אופציונלי) מציין העדפות למסלולי תחבורה ציבורית. באמצעות האפשרות הזו, אתם יכולים להטות את האפשרויות שמוחזרות, במקום לקבל את המסלול הטוב ביותר שמוגדר כברירת מחדל ונבחר על ידי ה-API. אפשר לציין את השדה הזה רק אם הבקשה כוללת מפתח API. אלה הערכים המותרים:
    • FEWER_TRANSFERS מציין שהמסלול המחושב צריך להעדיף מספר מוגבל של החלפות.
    • LESS_WALKING מציין שהמסלול המחושב צריך להעדיף כמויות מוגבלות של הליכה.

דוגמה לDirectionsRequest בתחבורה ציבורית:

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

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

אפשר לציין אפשרויות ניתוב למסלולי נסיעה באמצעות האובייקט DrivingOptions.

האובייקט DrivingOptions מכיל את השדות הבאים:

{
  departureTime: Date,
  trafficModel: TrafficModel
}

השדות האלה מוסברים בהמשך:

  • ‫departureTime (חובה כדי שהליטרל של האובייקט drivingOptions יהיה תקין) מציין את שעת היציאה הרצויה כאובייקט Date. הערך צריך להיות מוגדר לשעה הנוכחית או לשעה כלשהי בעתיד. התאריך לא יכול להיות בעבר. (ה-API ממיר את כל התאריכים ל-UTC כדי להבטיח טיפול עקבי בכל אזורי הזמן). אם אתם לקוחות של מינוי פרימיום לפלטפורמה של מפות Google, ואתם כוללים את הפרמטר departureTime בבקשה, ה-API מחזיר את המסלול הכי טוב בהתאם למצב התנועה הצפוי באותו זמן, וכולל בתגובה את זמן הנסיעה החזוי בהתאם למצב התנועה (duration_in_traffic). אם לא מציינים שעת יציאה (כלומר, אם הבקשה לא כוללת את drivingOptions), המסלול שמוחזר הוא בדרך כלל מסלול טוב שלא מביא בחשבון את מצב התנועה.
  • trafficModel (אופציונלי) מציין את ההנחות שבהן צריך להשתמש כשמחשבים את הזמן בתנועה. ההגדרה הזו משפיעה על הערך שמוחזר בשדה duration_in_traffic בתגובה, שמכיל את זמן הנסיעה החזוי בהתאם לממוצעים היסטוריים. ברירת המחדל היא bestguess. אלה הערכים המותרים:
    • ‫bestguess (ברירת המחדל) מציין שהערך המוחזר של duration_in_traffic צריך להיות האומדן הטוב ביותר של זמן ההגעה, בהתאם למידע הידוע על מצב התנועה ההיסטורי ועל מצב התנועה בזמן אמת. ככל שdepartureTime קרוב יותר לזמן הנוכחי, כך חשיבות התנועה בזמן אמת גדלה.
    • pessimistic מציין שהערך של duration_in_traffic שמוחזר צריך להיות ארוך יותר מזמן ההגעה בפועל ברוב הימים, אבל יכול להיות שבימים מסוימים עם מצב תנועה גרוע במיוחד, זמן ההגעה בפועל יהיה ארוך יותר מהערך הזה.
    • optimistic מציין שהערך המוחזר של duration_in_traffic צריך להיות קצר יותר מזמן ההגעה בפועל ברוב הימים, אבל יכול להיות שבימים מסוימים מצב התנועה יהיה טוב במיוחד והנסיעה תהיה מהירה יותר מהערך הזה.

בהמשך מופיעה דוגמה ל-DirectionsRequest של מסלול נסיעה:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

מערכות יחידות

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

  • ‫UnitSystem.METRIC מציין שימוש במערכת המטרית. המרחקים מוצגים בקילומטרים.
  • UnitSystem.IMPERIAL מציין שימוש במערכת המידות האימפריאלית (האנגלית). המרחקים מוצגים במיילים.

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

הטיית אזור להוראות הגעה

שירות המסלולים של Google Maps API מחזיר תוצאות של כתובות שמושפעות מהדומיין (אזור או מדינה) שממנו טענתם את ה-bootstrap של JavaScript. (מכיוון שרוב המשתמשים טוענים את https://maps.googleapis.com/, הדומיין המשתמע הוא ארצות הברית). אם טוענים את ה-bootstrap מדומיין נתמך אחר, מקבלים תוצאות שמושפעות מהדומיין הזה. לדוגמה, חיפושים של "San Francisco" עשויים להחזיר תוצאות שונות מאפליקציות שטוענות את https://maps.googleapis.com/ (ארצות הברית) לעומת אפליקציות שטוענות את http://maps.google.es/ (ספרד).

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

כשמשתמשים בפרמטר region:

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

הטיית אזור נתמכת רק במדינות ובאזורים שבהם יש תמיכה במסלולים. בפרטי הכיסוי של Google Maps Platform אפשר לראות את הכיסוי הבינלאומי של Directions API (דור קודם).

הצגת המסלול

כדי לשלוח בקשה לקבלת מסלול אל DirectionsService באמצעות השיטה route(), צריך להעביר פונקציית קריאה חוזרת (callback) שמופעלת בסיום בקשת השירות. הקריאה החוזרת הזו תחזיר DirectionsResult וקוד DirectionsStatus בתגובה.

סטטוס השאילתה לקבלת מסלול הגעה

השדה DirectionsStatus יכול להחזיר את הערכים הבאים:

  • ‫OK מציין שהתשובה מכילה DirectionsResult תקין.
  • הערך NOT_FOUND מציין שלא ניתן היה להמיר לקואורדינטות לפחות אחד מהמיקומים שצוינו בנקודת המוצא, בנקודת היעד או בנקודות הדרך של הבקשה.
  • הערך ZERO_RESULTS מציין שלא נמצא מסלול בין נקודת המוצא ליעד.
  • ‫MAX_WAYPOINTS_EXCEEDED מציין שסופקו יותר מדי שדות של DirectionsWaypoint ב-DirectionsRequest. אפשר לעיין בקטע שבהמשך בנושא מגבלות על נקודות ציון.
  • MAX_ROUTE_LENGTH_EXCEEDED מציין שהמסלול המבוקש ארוך מדי ואי אפשר לעבד אותו. השגיאה הזו מתרחשת כשמוחזרות הנחיות מורכבות יותר. כדאי לנסות לצמצם את מספר נקודות הדרך, הפניות או ההוראות.
  • ‫INVALID_REQUEST מציין שהערך שצוין בשדה DirectionsRequest לא תקין. הסיבות הנפוצות ביותר לקוד השגיאה הזה הן בקשות שחסר בהן מקור או יעד, או בקשה לתחבורה ציבורית שכוללת נקודות דרך.
  • OVER_QUERY_LIMIT מציין שדף האינטרנט שלח יותר מדי בקשות בפרק הזמן המותר.
  • הערך REQUEST_DENIED מציין שלדף האינטרנט אין הרשאה להשתמש בשירות המסלולים.
  • ‫UNKNOWN_ERROR מציין שלא ניתן היה לעבד בקשה לקבלת מסלול בגלל שגיאה בחיבור לשרת. יכול להיות שהבקשה תצליח אם תנסו שוב.

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

הצגת DirectionsResult

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

כדי להציג DirectionsResult באמצעות DirectionsRenderer, צריך לבצע את הפעולות הבאות:

  1. יוצרים אובייקט DirectionsRenderer.
  2. מפעילים את setMap() בכלי הרינדור כדי לקשר אותו למפה שהועברה.
  3. מפעילים את setDirections() ב-renderer ומעבירים אליו את DirectionsResult, כמו שצוין למעלה. מכיוון שהכלי לעיבוד הוא MVCObject, הוא יזהה באופן אוטומטי כל שינוי במאפיינים שלו ויעדכן את המפה כשהמסלול המשויך ישתנה.

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

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin: start,
    destination: end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(result, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(result);
    }
  });
}

בגוף ה-HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

להצגת דוגמה

בדוגמה הבאה מוצגות הוראות הגעה באמצעי תחבורה שונים בין Haight-Ashbury ל-Ocean Beach בסן פרנסיסקו, קליפורניה:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

בגוף ה-HTML:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

להצגת דוגמה

האובייקט DirectionsRenderer לא רק מטפל בהצגת הקו הפוליגוני וכל הסמנים המשויכים, אלא גם יכול לטפל בהצגת הטקסט של המסלול כסדרה של שלבים. כדי לעשות את זה, צריך להפעיל את setPanel() ב-DirectionsRenderer ולהעביר את <div> שבו רוצים להציג את המידע הזה. כך גם תוכלו להציג את פרטי זכויות היוצרים המתאימים ואת כל האזהרות שעשויות להיות משויכות לתוצאה.

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

הדוגמה הבאה זהה לדוגמה שלמעלה, אבל כוללת חלונית <div> שבה מוצגות ההוראות:

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var chicago = new google.maps.LatLng(41.850033, -87.6500523);
  var mapOptions = {
    zoom:7,
    center: chicago
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
  directionsRenderer.setPanel(document.getElementById('directionsPanel'));
}

function calcRoute() {
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
    origin:start,
    destination:end,
    travelMode: 'DRIVING'
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

בגוף ה-HTML:

<div id="map" style="float:left;width:70%;height:100%"></div>
<div id="directionsPanel" style="float:right;width:30%;height:100%"></div>

להצגת דוגמה

האובייקט DirectionsResult

כששולחים בקשה לקבלת מסלול אל DirectionsService, מקבלים תשובה שמורכבת מקוד סטטוס ומתוצאה, שהיא אובייקט DirectionsResult. הפרמטר DirectionsResult הוא ליטרל של אובייקט עם השדות הבאים:

  • ‫geocoded_waypoints[] מכיל מערך של אובייקטים מסוג DirectionsGeocodedWaypoint, שכל אחד מהם מכיל פרטים על המרת הכתובות לקואורדינטות של נקודת המוצא, היעד ונקודות הדרך.
  • ‫routes[] מכיל מערך של אובייקטים מסוג DirectionsRoute. כל מסלול מציין דרך להגיע מנקודת המוצא ליעד שצוינו ב-DirectionsRequest. בדרך כלל, כל בקשה מחזירה רק מסלול אחד, אלא אם השדה provideRouteAlternatives של הבקשה מוגדר לערך true, ואז יכולים להיות כמה מסלולים.

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

נקודות דרך עם המרת כתובות לקואורדינטות (geocoding) במסלול הגעה

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

השדה DirectionsGeocodedWaypoint הוא ליטרל של אובייקט עם השדות הבאים:

  • השדה geocoder_status מציין את קוד הסטטוס שנוצר כתוצאה מהמרת הכתובת לקואורדינטות. השדה הזה יכול להכיל את הערכים הבאים.
    • הערך "OK" מציין שלא היו שגיאות, הכתובת נותחה בהצלחה והוחזרו לפחות קואורדינטות אחת.
    • הערך "ZERO_RESULTS" מציין שהמרת הכתובת לקואורדינטות בוצעה בהצלחה, אבל לא הוחזרו תוצאות. זה יכול לקרות אם לכלי להמרת כתובות לקואורדינטות (geocoder) הועבר address שלא קיים.

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

    התאמות חלקיות מתרחשות בדרך כלל בכתובות רחוב שלא קיימות ביישוב שאתם מעבירים בבקשה. יכול להיות שיוחזרו התאמות חלקיות גם כשבקשה תואמת לשני מיקומים או יותר באותו יישוב. לדוגמה, "Hillpar St, Bristol, UK" יחזיר התאמה חלקית גם ל-Henry Street וגם ל-Henrietta Street. שימו לב: אם הבקשה כוללת רכיב כתובת עם שגיאת כתיב, יכול להיות ששירות המרת הכתובות לקואורדינטות יציע כתובת חלופית. הצעות שמוצגות בגלל התאמה כזו יסומנו גם כהתאמה חלקית.

  • place_id הוא מזהה ייחודי של מקום, שאפשר להשתמש בו עם ממשקי Google API אחרים. לדוגמה, אפשר להשתמש ב-place_id עם הספרייה Google Places API כדי לקבל פרטים על עסק מקומי, כמו מספר טלפון, שעות פתיחה, ביקורות של משתמשים ועוד. סקירה כללית על מזהי מקומות
  • ‫types[] הוא מערך שמציין את הסוג של התוצאה שהוחזרה. המערך הזה מכיל קבוצה של אפס תגים או יותר שמזהים את סוג התכונה שמוחזרת בתוצאה. לדוגמה, קואורדינטות של "שיקגו" מחזירות את הערך locality, שמציין ש"שיקגו" היא עיר, וגם את הערך political, שמציין שהיא ישות פוליטית.

מסלולי הגעה

הערה: השם של האובייקט DirectionsTrip מהדור הקודם השתנה ל-DirectionsRoute. שימו לב שעכשיו מסלול מתייחס לכל הנסיעה מההתחלה ועד הסוף, ולא רק למקטע של נסיעה ראשית.

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

השדה DirectionsRoute הוא ליטרל של אובייקט עם השדות הבאים:

  • השדה legs[] מכיל מערך של אובייקטים מסוג DirectionsLeg, שכל אחד מהם מכיל מידע על מקטע במסלול, בין שני מיקומים במסלול הנתון. לכל נקודת ציון או יעד שצוינו יהיה מקטע נפרד. (מסלול בלי נקודות ציון יכיל בדיוק DirectionsLeg אחד). כל מקטע מורכב מסדרה של DirectionStep.
  • waypoint_order מכיל מערך שמציין את הסדר של נקודות הדרך במסלול המחושב. המערך הזה עשוי להכיל סדר שונה אם הועבר DirectionsRequest optimizeWaypoints: true.
  • השדה overview_path מכיל מערך של אובייקטים מסוג LatLng שמייצגים מסלול משוער (מוחלק) של המסלול שנוצר.
  • השדה overview_polyline מכיל אובייקט points אחד שמכיל ייצוג של המסלול באמצעות קו פוליגוני מקודד. הקו הפוליגוני הזה הוא מסלול משוער (מוחלק) של המסלול שנוצר.
  • השדה bounds מכיל LatLngBounds שמציין את גבולות הקו הפוליגוני לאורך המסלול הנתון.
  • ‫copyrights מכיל את הטקסט של זכויות היוצרים שיוצג במסלול הזה.
  • warnings[] מכיל מערך של אזהרות שיוצגו כשמציגים את המסלולים האלה. אם לא משתמשים באובייקט DirectionsRenderer שסופק, צריך לטפל באזהרות האלה ולהציג אותן בעצמכם.
  • השדה fare מכיל את מחיר הנסיעה הכולל (כלומר, העלות הכוללת של הכרטיסים) במסלול הזה. המאפיין הזה מוחזר רק לבקשות של תחבורה ציבורית ורק למסלולים שבהם מידע על התעריף זמין לכל מקטעי התחבורה הציבורית. המידע כולל:
    • ‫currency: קוד מטבע בתקן ISO 4217 שמציין את המטבע שבו הסכום מבוטא.
    • ‫value: הסכום הכולל של התעריף, במטבע שצוין למעלה.

מקטעי מסלול

הערה: השם של האובייקט DirectionsRoute מהדור הקודם השתנה ל-DirectionsLeg.

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

האובייקט DirectionsLeg הוא ליטרל של אובייקט עם השדות הבאים:

  • ‫steps[] מכיל מערך של אובייקטים מסוג DirectionsStep שמציינים מידע על כל שלב נפרד בקטע של המסלול.

  • ‫distance מציין את המרחק הכולל של המקטע הזה, כאובייקט Distance בפורמט הבא:

    • ‫value מציין את המרחק במטרים
    • השדה text מכיל ייצוג של המרחק כמחרוזת, שמוצג כברירת מחדל ביחידות שבהן משתמשים בנקודת המוצא. (לדוגמה, אם נקודת המוצא היא בארצות הברית, המרחק יוצג במיילים). אפשר לשנות את מערכת היחידות הזו על ידי הגדרה ספציפית של UnitSystem בשאילתה המקורית. חשוב לזכור שלא משנה באיזו מערכת יחידות אתם משתמשים, השדה distance.value תמיד מכיל ערך במטרים.

    יכול להיות שהשדות האלה לא יוגדרו אם המרחק לא ידוע.

  • ‫duration מציין את משך הזמן הכולל של הקטע הזה, כאובייקט Duration בפורמט הבא:

    • ‫value מציין את משך הזמן בשניות.
    • ‫text מכיל ייצוג מחרוזת של משך הזמן.

    יכול להיות שהשדות האלה לא יהיו מוגדרים אם משך הזמן לא ידוע.

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

    • הבקשה לא כוללת נקודות עצירה. כלומר, הוא לא כולל נקודות ציון שבהן הערך של stopover הוא true.
    • הבקשה היא ספציפית למסלול נסיעה – הערך של mode מוגדר כ-driving.
    • השדה departureTime נכלל כחלק מהשדה drivingOptions בבקשה.
    • מצב התנועה זמין במסלול המבוקש.

    ה-duration_in_traffic מכיל את השדות הבאים:

    • ‫value מציין את משך הזמן בשניות.
    • ‫text מכיל ייצוג קריא לאנשים של משך הזמן.
  • ‫arrival_time מכיל את זמן ההגעה המשוער של המקטע הזה. המאפיין הזה מוחזר רק במסלולים לתחבורה ציבורית. התוצאה מוחזרת כאובייקט Time עם שלושה מאפיינים:
    • ‫value הזמן שצוין כאובייקט Date ב-JavaScript.
    • ‫text הזמן שצוין כמחרוזת. השעה מוצגת באזור הזמן של תחנת התחבורה הציבורית.
    • השדה time_zone מכיל את אזור הזמן של התחנה הזו. הערך הוא השם של אזור הזמן כפי שמוגדר במסד הנתונים של אזורי הזמן של IANA, למשל "America/New_York".
  • ‫departure_time מכיל את זמן היציאה המשוער של הקטע הזה, שצוין כאובייקט Time. השדה departure_time זמין רק במסלולים לתחבורה ציבורית.
  • ‫start_location מכיל את LatLng של נקודת המוצא של הקטע הזה. מכיוון ששירות האינטרנט Directions מחשב מסלולים בין מיקומים באמצעות אפשרות התחבורה הקרובה ביותר (בדרך כלל כביש) בנקודות ההתחלה והסיום, יכול להיות שהערך של start_location יהיה שונה מנקודת המוצא שצוינה למקטע הזה, למשל אם אין כביש קרוב לנקודת המוצא.
  • ‫end_location מכיל את LatLng של היעד של המקטע הזה. ‫DirectionsService מחשב מסלולים בין מיקומים באמצעות אפשרות התחבורה הקרובה ביותר (בדרך כלל כביש) בנקודות ההתחלה והסיום, לכן יכול להיות ש-end_location יהיה שונה מהיעד שצוין למקטע הזה, למשל אם אין כביש ליד היעד.
  • start_address מכיל את הכתובת הקריאה לאנשים (בדרך כלל כתובת רחוב) של תחילת הקטע הזה.

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

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

שלבים במסלול

DirectionsStep הוא היחידה האטומית ביותר של מסלול, והוא מכיל שלב אחד שמתאר הוראה ספציפית אחת במסלול. לדוגמה: "פנה שמאלה ברחוב W. ‫4th St." השלב לא רק מתאר את ההוראה, אלא גם מכיל מידע על המרחק ומשך הזמן שקשורים לאופן שבו השלב הזה קשור לשלב הבא. לדוגמה, שלב שמסומן כ-"Merge onto I-80 West" עשוי להכיל משך זמן של "37 miles" ו-"40 minutes", מה שמציין שהשלב הבא נמצא במרחק של 37 מיילים או 40 דקות מהשלב הזה.

כשמשתמשים בשירות Directions כדי לחפש מסלול לתחבורה ציבורית, מערך השלבים יכלול מידע ספציפי נוסף על התחבורה הציבורית בצורת אובייקט transit. אם המסלול כולל כמה אמצעי תחבורה, הוראות מפורטות להליכה או לנהיגה יופיעו במערך steps[]. לדוגמה, שלב הליכה יכלול הוראות ממיקום ההתחלה ועד למיקום הסיום: "הולכים אל Innes Ave & Fitch St". השלב הזה יכלול מסלול הליכה מפורט באותו נתיב במערך steps[], למשל: "פונים לכיוון צפון-מערב", "פונים שמאלה אל Arelious Walker" ו"פונים שמאלה אל Innes Ave".

האובייקט DirectionsStep הוא ליטרל של אובייקט עם השדות הבאים:

  • instructions מכיל הוראות לשלב הזה בתוך מחרוזת טקסט.
  • השדה distance מכיל את המרחק שעוברים בשלב הזה עד לשלב הבא, כאובייקט Distance. (ראו את התיאור ב-DirectionsLeg למעלה). יכול להיות שהשדה הזה לא יהיה מוגדר אם המרחק לא ידוע.
  • השדה duration מכיל אומדן של הזמן שנדרש כדי לבצע את השלב, עד לשלב הבא, כאובייקט Duration. (ראו את התיאור בDirectionsLeg למעלה). יכול להיות שהשדה הזה לא יהיה מוגדר אם משך הזמן לא ידוע.
  • השדה start_location מכיל את הLatLng של נקודת ההתחלה של השלב הזה, אחרי המרת הכתובת לקואורדינטות.
  • ‫end_location מכיל את LatLng של נקודת הסיום של השלב הזה.
  • ‫polyline מכיל אובייקט points אחד שמכיל ייצוג של קו פוליגוני מקודד של השלב. הקו הפוליגוני הזה הוא נתיב משוער (מוחלק) של השלב.
  • ‫steps[] ליטרל של אובייקט DirectionsStep שמכיל הוראות מפורטות להליכה או לנהיגה במסלול לתחבורה ציבורית. שלבי משנה זמינים רק במסלולים לתחבורה ציבורית.
  • ‫travel_mode מכיל את ה-TravelMode שמשמש בשלב הזה. מסלול לתחבורה ציבורית יכול לכלול שילוב של מסלול הליכה ומסלול לתחבורה ציבורית.
  • ‫path מכיל מערך של LatLngs שמתאר את המסלול של השלב הזה.
  • השדה transit מכיל מידע ספציפי על התחבורה הציבורית, כמו זמני ההגעה והיציאה ושם קו התחבורה הציבורית.

מידע ספציפי לגבי תחבורה ציבורית

מסלולים לתחבורה ציבורית מחזירים מידע נוסף שלא רלוונטי לאמצעי תחבורה אחרים. המאפיינים הנוספים האלה נחשפים דרך האובייקט TransitDetails, שמוחזר כמאפיין של DirectionsStep. מהאובייקט TransitDetails אפשר לגשת למידע נוסף על האובייקטים TransitStop,‏ TransitLine,‏ TransitAgency ו-VehicleType, כמו שמתואר בהמשך.

פרטי התחבורה הציבורית

האובייקט TransitDetails חושף את המאפיינים הבאים:

  • ‫arrival_stop מכיל אובייקט מסוג TransitStop שמייצג את תחנת ההגעה, עם המאפיינים הבאים:
    • name את השם של התחנה של התחבורה הציבורית. למשל "Union Square".
    • ‫location המיקום של התחנה של התחבורה הציבורית, מיוצג כ-LatLng.
  • ‫departure_stop מכיל אובייקט TransitStop שמייצג את תחנת היציאה.
  • arrival_time מכיל את זמן ההגעה, שצוין כאובייקט Time עם שלושה מאפיינים:
    • ‫value הזמן שצוין כאובייקט Date ב-JavaScript.
    • ‫text הזמן שצוין כמחרוזת. השעה מוצגת באזור הזמן של תחנת התחבורה הציבורית.
    • השדה time_zone מכיל את אזור הזמן של התחנה הזו. הערך הוא השם של אזור הזמן כפי שמוגדר במסד הנתונים של אזורי הזמן של IANA, למשל "America/New_York".
  • ‫departure_time מכיל את שעת היציאה, שצוינה כאובייקט Time.
  • headsign מציין את כיוון הנסיעה בקו הזה, כפי שהוא מסומן על כלי הרכב או בתחנת היציאה. בדרך כלל זו תהיה התחנה הסופית.
  • headway אם זמין, מציין את מספר השניות הצפוי בין יציאות מאותה תחנה בזמן הזה. לדוגמה, אם הערך של headway הוא 600, זמן ההמתנה הצפוי אם פספסתם את האוטובוס הוא 10 דקות.
  • line מכיל ליטרל של אובייקט TransitLine שמכיל מידע על קו התחבורה הציבורית שמשמש בשלב הזה. השדה TransitLine מספק את השם והמפעיל של הקו, יחד עם מאפיינים אחרים שמתוארים במאמרי העזרה של TransitLine.
  • num_stops מכיל את מספר התחנות בשלב הזה. כולל את תחנת ההגעה, אבל לא את תחנת היציאה. לדוגמה, אם המסלול כולל יציאה מתחנה א', מעבר בתחנות ב' וג' והגעה לתחנה ד', הפונקציה num_stops תחזיר את הערך 3.

קו תחבורה ציבורית

האובייקט TransitLine חושף את המאפיינים הבאים:

  • השדה name מכיל את השם המלא של קו התחבורה הציבורית הזה. לדוגמה: "7 Avenue Express" או "14th St Crosstown".
  • ‫short_name מכיל את השם המקוצר של קו התחבורה הציבורית הזה. בדרך כלל זה יהיה מספר קו, כמו "2" או "M14".
  • ‫agencies הוא מערך שמכיל אובייקט TransitAgency אחד. האובייקט TransitAgency מספק מידע על המפעיל של הקו הזה, כולל המאפיינים הבאים:
    • ‫name מכיל את השם של חברת התחבורה הציבורית.
    • השדה phone מכיל את מספר הטלפון של חברת התחבורה הציבורית.
    • השדה url מכיל את כתובת ה-URL של חברת התחבורה הציבורית.

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

  • url מכיל כתובת URL של קו התחבורה הציבורית הזה, כפי שסופקה על ידי חברת התחבורה הציבורית.
  • העמודה icon מכילה כתובת URL של הסמל שמשויך לשורה הזו. ברוב הערים יוצגו סמלים גנריים שמשתנים בהתאם לסוג הרכב. לחלק מקווי התחבורה הציבורית, כמו הרכבת התחתית של ניו יורק, יש סמלים ספציפיים לקו הזה.
  • color מכיל את הצבע שמשמש בדרך כלל בשילוט של אמצעי התחבורה הזה. הצבע יצוין כמחרוזת הקסדצימלית, למשל: ‎#FF0033.
  • text_color מכיל את צבע הטקסט שמשמש בדרך כלל לשילוט של הקו הזה. הצבע יצוין כמחרוזת הקסדצימלית.
  • ‫vehicle מכיל אובייקט Vehicle שכולל את המאפיינים הבאים:
    • בעמודה name מופיע שם הרכב בשורה הזו. למשל "Subway".
    • העמודה type מכילה את סוג הרכב שמשמש בקו הזה. רשימה מלאה של הערכים הנתמכים מופיעה במסמכי התיעוד של סוג כלי רכב.
    • ‫icon מכיל כתובת URL של הסמל שמשויך בדרך כלל לסוג כלי הרכב הזה.
    • local_icon מכיל את כתובת ה-URL של הסמל שמשויך לסוג כלי הרכב הזה, על סמך השילוט של התחבורה המקומית.

סוג הרכב

האובייקט VehicleType חושף את המאפיינים הבאים:

ערך הגדרה
VehicleType.RAIL רכבת.
VehicleType.METRO_RAIL רכבת קלה.
VehicleType.SUBWAY רכבת קלה תת-קרקעית.
VehicleType.TRAM רכבת קלה עילית.
VehicleType.MONORAIL רכבת מונורייל.
VehicleType.HEAVY_RAIL רכבת כבדה.
VehicleType.COMMUTER_TRAIN רכבת פרברים.
VehicleType.HIGH_SPEED_TRAIN רכבת מהירה.
VehicleType.BUS אוטובוס.
VehicleType.INTERCITY_BUS אוטובוס בין-עירוני.
VehicleType.TROLLEYBUS אוטובוס חשמלי.
VehicleType.SHARE_TAXI מונית שירות היא סוג של אוטובוס שיכול להוריד ולאסוף נוסעים בכל מקום לאורך המסלול שלו.
VehicleType.FERRY מעבורת.
VehicleType.CABLE_CAR כלי רכב שפועל על כבל, בדרך כלל על הקרקע. רכבלים יכולים להיות מסוג VehicleType.GONDOLA_LIFT.
VehicleType.GONDOLA_LIFT רכבל.
VehicleType.FUNICULAR רכב שנמשך במעלה שיפוע תלול באמצעות כבל. פוניקולר מורכב בדרך כלל משני קרונות, כאשר כל קרון משמש כמשקל נגד לשני.
VehicleType.OTHER כל שאר הרכבים יחזירו את הסוג הזה.

בדיקת DirectionsResults

יכול להיות שהרכיבים של DirectionsResults – DirectionsRoute,‏ DirectionsLeg,‏ DirectionsStep ו-TransitDetails – ייבדקו וישמשו לניתוח של כל תגובה לבקשת מסלול.

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

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

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

var map;
var directionsRenderer;
var directionsService;
var stepDisplay;
var markerArray = [];

function initMap() {
  // Instantiate a directions service.
  directionsService = new google.maps.DirectionsService();

  // Create a map and center it on Manhattan.
  var manhattan = new google.maps.LatLng(40.7711329, -73.9741874);
  var mapOptions = {
    zoom: 13,
    center: manhattan
  }
  map = new google.maps.Map(document.getElementById('map'), mapOptions);

  // Create a renderer for directions and bind it to the map.
  var rendererOptions = {
    map: map
  }
  directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions)

  // Instantiate an info window to hold step text.
  stepDisplay = new google.maps.InfoWindow();
}

function calcRoute() {

  // First, clear out any existing markerArray
  // from previous calculations.
  for (i = 0; i < markerArray.length; i++) {
    markerArray[i].setMap(null);
  }

  // Retrieve the start and end locations and create
  // a DirectionsRequest using WALKING directions.
  var start = document.getElementById('start').value;
  var end = document.getElementById('end').value;
  var request = {
      origin: start,
      destination: end,
      travelMode: 'WALKING'
  };

  // Route the directions and pass the response to a
  // function to create markers for each step.
  directionsService.route(request, function(response, status) {
    if (status == "OK") {
      var warnings = document.getElementById("warnings_panel");
      warnings.innerHTML = "" + response.routes[0].warnings + "";
      directionsRenderer.setDirections(response);
      showSteps(response);
    }
  });
}

function showSteps(directionResult) {
  // For each step, place a marker, and add the text to the marker's
  // info window. Also attach the marker to an array so we
  // can keep track of it and remove it when calculating new
  // routes.
  var myRoute = directionResult.routes[0].legs[0];

  for (var i = 0; i < myRoute.steps.length; i++) {
      var marker = new google.maps.Marker({
        position: myRoute.steps[i].start_point,
        map: map
      });
      attachInstructionText(marker, myRoute.steps[i].instructions);
      markerArray[i] = marker;
  }
}

function attachInstructionText(marker, text) {
  google.maps.event.addListener(marker, 'click', function() {
    stepDisplay.setContent(text);
    stepDisplay.open(map, marker);
  });
}

בגוף ה-HTML:

<div>
<strong>Start: </strong>
<select id="start">
  <option value="penn station, new york, ny">Penn Station</option>
  <option value="grand central station, new york, ny">Grand Central Station</option>
  <option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
  <option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
  <option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="260 Broadway New York NY 10007">City Hall</option>
  <option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
  <option value="moma, New York, NY">MOMA</option>
  <option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
  <option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
  <option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>

להצגת דוגמה

שימוש בנקודות ציון במסלולים

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

‫waypoint מורכב מהשדות הבאים:

  • ‫location (חובה) מציין את הכתובת של נקודת הדרך.
  • ‫stopover (אופציונלי) מציין אם נקודת הדרך הזו היא עצירה בפועל במסלול (true) או רק העדפה למסלול שעובר במיקום שצוין (false). עצירות הביניים הן true כברירת מחדל.

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

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

בדוגמה הבאה מחושבים מסלולים ברחבי ארצות הברית באמצעות מגוון נקודות התחלה, נקודות סיום ונקודות ציון. (כדי לבחור כמה נקודות דרך, לוחצים על Ctrl-Click כשבוחרים פריטים ברשימה). שימו לב שאנחנו בודקים את routes.start_address ואת routes.end_address כדי לקבל את הטקסט של נקודת ההתחלה והסיום של כל מסלול.

TypeScript

function initMap(): void {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 6,
      center: { lat: 41.85, lng: -87.65 },
    }
  );

  directionsRenderer.setMap(map);

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      calculateAndDisplayRoute(directionsService, directionsRenderer);
    }
  );
}

function calculateAndDisplayRoute(
  directionsService: google.maps.DirectionsService,
  directionsRenderer: google.maps.DirectionsRenderer
) {
  const waypts: google.maps.DirectionsWaypoint[] = [];
  const checkboxArray = document.getElementById(
    "waypoints"
  ) as HTMLSelectElement;

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: (checkboxArray[i] as HTMLOptionElement).value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: (document.getElementById("start") as HTMLInputElement).value,
      destination: (document.getElementById("end") as HTMLInputElement).value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById(
        "directions-panel"
      ) as HTMLElement;

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer();
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 6,
    center: { lat: 41.85, lng: -87.65 },
  });

  directionsRenderer.setMap(map);
  document.getElementById("submit").addEventListener("click", () => {
    calculateAndDisplayRoute(directionsService, directionsRenderer);
  });
}

function calculateAndDisplayRoute(directionsService, directionsRenderer) {
  const waypts = [];
  const checkboxArray = document.getElementById("waypoints");

  for (let i = 0; i < checkboxArray.length; i++) {
    if (checkboxArray.options[i].selected) {
      waypts.push({
        location: checkboxArray[i].value,
        stopover: true,
      });
    }
  }

  directionsService
    .route({
      origin: document.getElementById("start").value,
      destination: document.getElementById("end").value,
      waypoints: waypts,
      optimizeWaypoints: true,
      travelMode: google.maps.TravelMode.DRIVING,
    })
    .then((response) => {
      directionsRenderer.setDirections(response);

      const route = response.routes[0];
      const summaryPanel = document.getElementById("directions-panel");

      summaryPanel.innerHTML = "";

      // For each route, display summary information.
      for (let i = 0; i < route.legs.length; i++) {
        const routeSegment = i + 1;

        summaryPanel.innerHTML +=
          "<b>Route Segment: " + routeSegment + "</b><br>";
        summaryPanel.innerHTML += route.legs[i].start_address + " to ";
        summaryPanel.innerHTML += route.legs[i].end_address + "<br>";
        summaryPanel.innerHTML += route.legs[i].distance.text + "<br><br>";
      }
    })
    .catch((e) => window.alert("Directions request failed due to " + status));
}

window.initMap = initMap;

מגבלות והגבלות על נקודות ציון

מגבלות השימוש הבאות חלות:

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

מסלולים שניתן לגרור

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

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

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

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

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 4,
      center: { lat: -24.345, lng: 134.46 }, // Australia.
    }
  );

  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel") as HTMLElement,
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });

  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer
  );
}

function displayRoute(
  origin: string,
  destination: string,
  service: google.maps.DirectionsService,
  display: google.maps.DirectionsRenderer
) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result: google.maps.DirectionsResult) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result: google.maps.DirectionsResult) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i]!.distance!.value;
  }

  total = total / 1000;
  (document.getElementById("total") as HTMLElement).innerHTML = total + " km";
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 4,
    center: { lat: -24.345, lng: 134.46 }, // Australia.
  });
  const directionsService = new google.maps.DirectionsService();
  const directionsRenderer = new google.maps.DirectionsRenderer({
    draggable: true,
    map,
    panel: document.getElementById("panel"),
  });

  directionsRenderer.addListener("directions_changed", () => {
    const directions = directionsRenderer.getDirections();

    if (directions) {
      computeTotalDistance(directions);
    }
  });
  displayRoute(
    "Perth, WA",
    "Sydney, NSW",
    directionsService,
    directionsRenderer,
  );
}

function displayRoute(origin, destination, service, display) {
  service
    .route({
      origin: origin,
      destination: destination,
      waypoints: [
        { location: "Adelaide, SA" },
        { location: "Broken Hill, NSW" },
      ],
      travelMode: google.maps.TravelMode.DRIVING,
      avoidTolls: true,
    })
    .then((result) => {
      display.setDirections(result);
    })
    .catch((e) => {
      alert("Could not display directions due to: " + e);
    });
}

function computeTotalDistance(result) {
  let total = 0;
  const myroute = result.routes[0];

  if (!myroute) {
    return;
  }

  for (let i = 0; i < myroute.legs.length; i++) {
    total += myroute.legs[i].distance.value;
  }

  total = total / 1000;
  document.getElementById("total").innerHTML = total + " km";
}

window.initMap = initMap;
להצגת דוגמה