שירות מסלולים

סקירה כללית

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

כשמציינים את נקודת המוצא או היעד בבקשה לקבלת מסלול, אפשר לציין מחרוזת שאילתה (לדוגמה, 'תל אביב, תל אביב-יפו' או '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.
  4. אם ה-API מופיע ברשימה, סימן שהכול מוכן. אם ה-API לא מופיע ברשימה, מפעילים אותו:
    1. בחלק העליון של הדף, בוחרים באפשרות ENABLE API כדי להציג את הכרטיסייה Library. לחלופין, בתפריט הימני, לוחצים על ספרייה.
    2. מחפשים את Directions API ובוחרים בו מרשימת התוצאות.
    3. לוחצים על הפעלה. בסיום התהליך, Directions API יופיע ברשימת ממשקי ה-API במרכז הבקרה.

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

תמחור

החל מ-16 ביולי 2018, תוכנית תמחור חדשה של תשלום לפי שימוש נכנסה לתוקף במפות Google, במסלולים ובמקומות. למידע נוסף על התמחור והמגבלות החדשות לשימוש בשירות 'מסלול הגעה' ב-JavaScript, קראו את המאמר שימוש וחיובים בנושא Directions API.

מדיניות

השימוש בשירות 'מסלולי הגעה' חייב להתבצע בהתאם למדיניות שמפורטת עבור Directions API.

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

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

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

המשתנה המטא-ליטרלי של האובייקט 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 (לדוגמה, 'תל אביב, תל אביב-יפו'), בתור ערך LatLng או בתור אובייקט Place. אם משתמשים באובייקט Place, אפשר לציין מזהה מקום, מחרוזת שאילתה או מיקום LatLng. אפשר לאחזר מזהי מקומות מהשירותים של המרת כתובות לקואורדינטות (geocoding), חיפוש מקומות והשלמה אוטומטית למקומות ב-Maps JavaScript API. דוגמה לשימוש במזהי מקומות מההשלמה האוטומטית למקומות מפורטת במאמר השלמה אוטומטית למקומות ומסלול הגעה.
  • destination (חובה) מציין את מיקום היעד שאליו רוצים לחשב מסלול. האפשרויות הן אותן אפשרויות שקיימות בשדה origin שמתואר למעלה.
  • travelMode (חובה) מציין את כלי התחבורה שבו יש להשתמש בזמן חישוב המסלול. הערכים החוקיים מפורטים בקטע אמצעי תחבורה בהמשך.
  • transitOptions (אופציונלי) מציין ערכים שחלים רק על בקשות שבהן הערך של travelMode הוא TRANSIT. הערכים החוקיים מתוארים בקטע אפשרויות תעבורה שבהמשך.
  • drivingOptions (אופציונלי) מציין ערכים שחלים רק על בקשות שבהן הערך של travelMode הוא DRIVING. הערכים החוקיים מתוארים בקטע אפשרויות נהיגה שבהמשך.
  • unitSystem (אופציונלי) מציין באיזו מערכת יחידות להשתמש כשמציגים את התוצאות. הערכים החוקיים מפורטים בקטע Unit Systems בהמשך.

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

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

כברירת מחדל, המסלול מחושב ומוצג לפי מערכת היחידות של המדינה או האזור שמהם מתחיל המסלול. (הערה: מקורות שמתוארים באמצעות קואורדינטות של קו אורך/קו רוחב במקום כתובות תמיד מוגדרים כברירת מחדל ליחידות מטריות). לדוגמה, במסלול מ-Chicago, IL‏ אל Toronto, ONT התוצאות יוצגו במיילים, ובמסלול ההפוך התוצאות יוצגו בקילומטרים. אפשר לשנות את מערכת היחידות הזו על ידי הגדרה מפורשת של מערכת יחידות בבקשה, באמצעות אחד מהערכים הבאים של UnitSystem:

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

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

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

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

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

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

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

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

הוראות לעיבוד

כדי להתחיל בקשת מסלול ל-DirectionsService באמצעות השיטה route(), צריך להעביר קריאה חוזרת (callback) שתתבצע בסיום בקשת השירות. קוד ה-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() במעבד, ומעבירים לו את 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, אפשר להמשיך להטמיע מסלולים שניתן לגרור באמצעות שירות המסלולים על ידי השבתת האפשרות לגרור מסלולים חלופיים. רק המסלול הראשי צריך להיות ניתן לגרירה. המשתמשים יכולים לגרור את המסלול הראשי עד שהוא תואם למסלול חלופי.

נקודות דרך שהומרו לקואורדינטות במסלול

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

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

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

    התאמות חלקיות מתרחשות לרוב בכתובות רחוב שלא קיימות ביישוב שציינתם בבקשה. יכול להיות שיתקבלו גם התאמות חלקיות כשבקשה תואמת לשני מיקומים או יותר באותה יישוב. לדוגמה, 'Hillpar St, Bristol, UK' תחזיר התאמה חלקית גם לרחוב Henry וגם לרחוב Henrietta. שימו לב שאם בקשה כוללת רכיב של כתובת עם שגיאת איות, שירות הגיאוקוד עשוי להציע כתובת חלופית. הצעות שתופעלו באופן הזה יסומנו גם כהתאמה חלקית.

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

מסלולי נסיעה

הערה: שם האובייקט הקודם 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 מכיל את המחיר הכולל (כלומר, סך עלויות הכרטיסים) במסלול הזה. המאפיין הזה מוחזר רק לבקשות לתחבורה ציבורית, ורק למסלולים שבהם נתוני התעריפים זמינים לכל השלבים בתחבורה הציבורית. המידע כולל:

Directions Legs

הערה: שם האובייקט הקודם 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 של המקור של הצעד הזה. מכיוון ששירות האינטרנט של מסלולי הגעה מחשב מסלולים בין מיקומים באמצעות אפשרות התחבורה הקרובה ביותר (בדרך כלל כביש) בנקודות ההתחלה והסיום, הערך של start_location עשוי להיות שונה מהמיקום שצוין כמיקום המוצא של הקטע הזה, אם, לדוגמה, אין כביש בקרבת המיקום הזה.
  • השדה end_location מכיל את LatLng של היעד של הקטע הזה. מכיוון ש-DirectionsService מחשב מסלולים בין מיקומים באמצעות אפשרות התחבורה הקרובה ביותר (בדרך כלל כביש) בנקודות ההתחלה והסיום, ייתכן ש-end_location יהיה שונה מהיעד שצוין לשלב הזה אם, לדוגמה, אין כביש ליד היעד.
  • השדה start_address מכיל את הכתובת (בדרך כלל רחוב ומספר) של תחילת המסלול, שאנשים יכולים לקרוא.

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

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

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

DirectionsStep היא הישות הבסיסית ביותר במסלול של הוראות הגעה, שמכילה שלב אחד שמתאר הוראה ספציפית אחת במסלול. לדוגמה: "Turn left at W. רחוב 4". השלב לא רק מתאר את ההוראה, אלא מכיל גם מידע על המרחק והמשך הזמן שקשורים לאופן שבו השלב הזה קשור לשלב הבא. לדוגמה, שלב שמסומן בתור 'מעבר לכביש I-80 מערב' עשוי לכלול משך זמן של '37 מייל' ו'40 דקות', שמציין שהשלב הבא נמצא במרחק 37 מייל/40 דקות מהשלב הזה.

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

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

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

מגבלות על נקודות דרך

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

  • המספר המקסימלי של נקודות דרך שמותר להשתמש בהן כשמשתמשים בשירות 'מסלולים' בממשק API של JavaScript במפות Google הוא 25, בנוסף לנקודת המוצא וליעד. המגבלות זהות גם לשירות האינטרנט של Directions API.
  • ב שירות האינטרנט של Directions API, הלקוחות יכולים להשתמש ב-25 נקודות ציון, בנוסף לנקודת המוצא וליעד.
  • לקוחות עם תוכנית פרימיום של פלטפורמת מפות Google יכולים להשתמש ב-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;
להצגת דוגמה

ניסיון של דוגמה