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

סקירה כללית

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

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

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

תחילת העבודה

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

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

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

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

תמחור

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

כללי מדיניות

השימוש בשירות המסלולים חייב להיות בהתאם לכללי המדיניות שמתוארים ב-Directions API.

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

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

כדי להשתמש במסלול ב-API של JavaScript במפות, צריך ליצור אובייקט מסוג 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 (לדוגמה, "שיקגו, IL"), כערך של LatLng או כאובייקט Place. אם משתמשים באובייקט Place, אפשר לציין place ID, מחרוזת שאילתה או מיקום ב-LatLng. ניתן לאחזר מזהי מקומות מהשירותים של קידוד גיאוגרפי, חיפוש מקום והשלמה אוטומטית של מקומות ב-API של JavaScript של מפות Google. הנה דוגמה לשימוש במזהי מקומות מהשלמה אוטומטית של מקומות, במאמר השלמה אוטומטית של מקומות ומסלול הגעה.
  • 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'
  }
}

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

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

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

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

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

רינדור מסלול

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

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

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

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

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

הצגת מסלול ההגעה

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

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

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

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

מסלולי נסיעה

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DirectionsStep הוא היחידה האטומית ביותר במסלול של כיוון מסוים, שמכילה שלב אחד שמתאר הוראה ספציפית יחידה לאורך המסלול. למשל, "פנה שמאלה ב-W. 4th St." בנוסף, שלב זה לא רק מתאר את ההוראה, אלא גם כולל מידע על המרחק ומשך הזמן שקשורים לשלב הבא. לדוגמה, שלב שמסומן כ-"Merge to I-80 West" עשוי להכיל משך זמן של '59 מיילים' ו-'40 דקות', שמציין שהשלב הבא נמצא במרחק 40 ק"מ מהשלב הזה.

כשמשתמשים בשירות 'מסלולים' כדי לחפש מסלול לתחבורה ציבורית, מערך השלבים יכלול עוד מידע ספציפי לתחבורה ציבורית בצורת אובייקט transit. אם המסלול כולל אמצעי תחבורה מרובים, הוראות מפורטות יסופקו לשלבי הליכה או נהיגה במערך steps[]. לדוגמה, שלב הליכה יכלול הוראות הגעה מנקודת ההתחלה והסיום: "Walk to Innes Ave & Fitch St". השלב הזה יכלול הוראות הליכה מפורטות למסלול הזה במערך steps[], כמו: "Head North-מערב", "פנה שמאלה אל ארניוס ווקר" ו-"פנה שמאלה אל Innes Ave".

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

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

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

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

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

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

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

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

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

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

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

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

סוג הרכב

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

Value הגדרה
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 — DirectionsRoute, DirectionsLeg, DirectionsStep ו-TransitDetails — עשויים להיבדק ולהשתמש בהם במהלך ניתוח התגובות למסלולים.

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

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

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

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

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

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

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

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

function calcRoute() {

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

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

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

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

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

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

בגוף ה-HTML:

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

להצגת דוגמה

שימוש בציוני דרך במסלול

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

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

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

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

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

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

TypeScript

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

  directionsRenderer.setMap(map);

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

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

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

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

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

      summaryPanel.innerHTML = "";

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

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

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
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

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

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

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

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

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

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

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

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

TypeScript

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

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

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

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

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

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

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

  if (!myroute) {
    return;
  }

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

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

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
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
להצגת דוגמה

רוצה לנסות דוגמה?