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

סקירה כללית

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

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

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

תחילת העבודה

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

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

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

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

תמחור

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

מדיניות

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

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

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

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

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

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

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

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

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

הטייה אזורית למסלולים

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

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

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

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

בגוף ה-HTML:

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

להצגת דוגמה

האובייקט Directions result

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

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

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

מסלולי מסלול

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

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

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

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

רגלי המסלול

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

שלבים במסלול

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

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

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

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

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

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

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

האובייקט TransitDetails חושף את התוכן הבא נכסים:

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

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

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

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

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

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

סוג הרכב

האובייקט VehicleType חושף את התוכן הבא נכסים:

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

בדיקת תוצאות של מסלול נסיעה

רכיבי DirectionsResults — 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 כשבוחרים פריטים מהרשימה). לתשומת ליבך, אנחנו בודקים את 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

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

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

  • המספר המרבי של ציוני דרך שמותר להשתמש בשירות 'מסלול הגעה' ב-Maps JavaScript API הוא 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
להצגת דוגמה

כדאי לנסות דוגמה