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

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

סקירה כללית

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

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

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

איך מתחילים

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

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

  1. נכנסים ל- Google Cloud Console.
  2. לוחצים על הלחצן Select a project, בוחרים את הפרויקט שהגדרתם ב-Maps JavaScript API ולוחצים על Open.
  3. ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את מסלול API.
  4. אם ה-API מופיע ברשימה, הכול מוכן. אם ה-API לא מופיע, מפעילים אותו:
    1. בחלק העליון של הדף, בוחרים באפשרות הפעלת API כדי להציג את הכרטיסייה ספרייה. לחלופין, בתפריט שמימין בוחרים באפשרות ספרייה.
    2. מחפשים את האפשרות API API ובוחרים אותה מרשימת התוצאות.
    3. לוחצים על הפעלה. בסיום התהליך, API API מופיע ברשימת ממשקי ה-API במרכז הבקרה.

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

תמחור

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

מדיניות

השימוש בשירות 'מסלולים' חייב להיות בהתאם למדיניות שנקבעה עבור ה-API של 'מסלולים'.

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

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

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

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

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

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

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

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

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

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

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

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

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

הטיה אזורית לקבלת מסלול

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

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

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

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

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

הנחיות לרינדור

שליחת בקשה לקבלת מסלול עבור DirectionsService עם השיטה route() מחייבת קריאה חוזרת (callback) המסתיימת עם השלמת בקשת השירות. השיחה החוזרת הזו תחזיר את DirectionsResult וקוד DirectionsStatus בתשובה.

הסטטוס של שאילתת מסלול

הפונקציה DirectionsStatus עשויה להחזיר את הערכים הבאים:

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

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

הצגת הוראות המסלול

הקובץ DirectionsResult מכיל את התוצאה של שאילתת המסלול, שאתה יכול לטפל בה בעצמך, או להעביר אל אובייקט 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>

לצפייה בדוגמה

הדוגמה הבאה מציגה מסלול נסיעה באמצעי נסיעה שונים בין הייט-אשבורי לאושן ביץ' בסן פרנסיסקו, קליפורניה:

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 של JavaScript באמצעות הפרמטר 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>

לצפייה בדוגמה

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

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

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

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

מסלולים

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

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

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

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

רגליים במסלול

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

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

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

  • steps[] מכיל מערך של DirectionsStep אובייקטים המציינים מידע לגבי כל שלב בתהליך.
  • distance מציין את המרחק הכולל המוחזר על ידי הרגל הזה, כאובייקט Distance בצורה הבאה:

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

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

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

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

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

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

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

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

    • value מציין את משך הזמן בשניות.
    • הקובץ text מכיל ייצוג אנושי של משך הזמן.
  • arrival_time כולל את זמן ההגעה המשוער לחלק הזה. הנכס הזה מוחזר רק לקבלת מסלול תחבורה ציבורית. התוצאה מוחזרת כאובייקט Time עם שלושה מאפיינים:
    • value הזמן שצוין כאובייקט JavaScript Date.
    • 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 הוא היחידה האטומית ביותר במסלול של מסלול, והוא מכיל שלב יחיד שמתאר הוראות ספציפיות ונפרדות לאורך המסלול. למשל, "פנייה שמאלה ברחוב רחוב 4" השלב הזה כולל לא רק את ההוראה, אלא גם פרטים לגבי המרחק ומשך הזמן הקשורים לשלב הזה. לדוגמה, שלב שמסומן כ"מיזוג ל-I-80 Western" עשוי להכיל משך של "37 מיילים" ו-"40 דקות", המציין שהשלב הבא הוא 37 מיילים/40 דקות מהשלב הזה.

כשמשתמשים בשירות 'מסלול', כדי לחפש מסלול לתחבורה ציבורית, מערך השלבים יכלול מידע ספציפי של תחבורה ציבורית בצורת אובייקט transit. אם המסלול כולל מספר אמצעי תחבורה, נספק מסלול מפורט להליכה או לנהיגה ברכב steps[]. לדוגמה, שלב הליכה יכלול מסלולי הליכה מהתחלה וממיקום הסיום: "הליכה אל שדרות אינס ופיץ' סטריט". שלב זה יכלול מסלולי הליכה מפורטים במסלול steps[] במערך, למשל: 'סע לכיוון צפון-מערב', 'פנה שמאלה לטיילת ארילוס' ו 'פנה שמאלה לשדרת אינס'.

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

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

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

  • name כולל את השם המלא של קו התחבורה הציבורית הזה, למשל "7שדרות אקספרס" או "הרחוב 14 תל אביב".
  • 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 כל כלי הרכב האחרים יחזירו את הסוג הזה.

בדיקת הוראות מסלול

הרכיבים 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>

לצפייה בדוגמה

שימוש בציוני דרך בנתיבים

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

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

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

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

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

JavaScript

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

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

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

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

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

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

      summaryPanel.innerHTML = "";

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

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

window.initMap = initMap;

מגבלות והגבלות על ציוני דרך

בכפוף להגבלות השימוש ולהגבלות הבאות:

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

דוגמה