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

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

סקירה כללית

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

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

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

תחילת העבודה

לפני שמשתמשים בשירות המסלולים ב-Maps JavaScript API, צריך לוודא קודם שממשק Directions API (Legacy) מופעל במסוף 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

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

תמחור

מידע על תמחור ומדיניות שימוש בשירות המסלולים ב-JavaScript זמין במאמר בנושא שימוש וחיוב ב-Directions API (גרסה קודמת).

מדיניות

השימוש בשירות 'הוראות הגעה' צריך להתבצע בהתאם למדיניות שמתוארת ב-Directions API (Legacy).

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

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

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

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

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

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

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

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

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

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

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

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

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

הצגת מסלולים

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

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

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

  • ‫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 מכיל מערך של ‫LatLngs שמייצגים נתיב משוער (מוחלק) של ההוראות שמתקבלות.
  • ‫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 הזמן שצוין כאובייקט JavaScript Date.
    • text השעה שצוינה כמחרוזת. השעה מוצגת באזור הזמן של תחנת המעבר.
    • השדה time_zone מכיל את אזור הזמן של התחנה. הערך הוא שם אזור הזמן כפי שמוגדר ב-IANA Time Zone Database, למשל 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 דקות מהשלב הזה.

כשמשתמשים בשירות 'הוראות הגעה' כדי לחפש מסלולים לתחבורה ציבורית, המערך steps יכלול מידע ספציפי על תחבורה ציבורית בצורה של אובייקט 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[] a DirectionsStep object literal that contains detailed directions for walking or driving steps in transit directions. השלבים המשניים זמינים רק בהוראות הגעה בתחבורה ציבורית.
  • ‫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 הזמן שצוין כאובייקט JavaScript Date.
    • 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 מכיל את סוג הרכב שבו נעשה שימוש בשורה הזו. רשימה מלאה של הערכים הנתמכים מופיעה במסמכי התיעוד בנושא סוג רכב.
    • ‫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) כשמחשבים מסלולים באמצעות שירות Directions למסלולי הליכה, רכיבה על אופניים או נסיעה. אי אפשר להוסיף נקודות עצירה למסלולים בתחבורה ציבורית. נקודות ציון מאפשרות לחשב מסלולים דרך מיקומים נוספים. במקרה כזה, המסלול שמוחזר עובר דרך נקודות הציון שצוינו.

waypoint כולל את השדות הבאים:

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

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

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

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

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;
index.js

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

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

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

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

משתמשים יכולים לשנות את המסלולים לרכיבה על אופניים, להליכה או לנהיגה שמוצגים באמצעות DirectionsRenderer באופן דינמי אם הם ניתנים לגרירה. כך משתמש יכול לבחור ולשנות מסלולים על ידי לחיצה וגרירה של הנתיבים שנוצרו במפה. כדי לציין אם התצוגה של רכיב ה-renderer מאפשרת גרירה של ההוראות, צריך להגדיר את המאפיין 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;
index.ts

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;
index.js
לצפייה בדוגמה

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