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

סקירה כללית

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

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

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

איך מתחילים

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

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

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

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

תמחור

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

כללי מדיניות

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

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

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

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

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

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

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

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

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

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

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

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

  • הפונקציה optimizeWaypoints (אופציונלי) מציינת שייתכן שהמסלול שמשתמש ב-waypoints שסופק עבר אופטימיזציה על ידי סידור מחדש של ציוני הדרך בסדר יעיל יותר. אם true, שירות המסלולים יחזיר את הערך waypoints שעבר סידור מחדש בשדה waypoint_order.(למידע נוסף, אפשר לעיין בקטע שימוש בציוני דרך בנתיבים בהמשך).
  • הערך provideRouteAlternatives (אופציונלי) כשהוא מוגדר כ-true מציין ששירות המסלול עשוי לספק בתגובה יותר מחלופה אחת של מסלול. הערה: אם תספק חלופות חלופיות, זמן התגובה מהשרת עשוי להיות ארוך יותר. אפשרות זו זמינה רק לבקשות ללא ציוני דרך בינוניים.
  • avoidFerries (אופציונלי) כאשר הוא מוגדר ל-true, מציין שהנתיבים המחושבים נמנעים ממעבורות, אם ניתן.
  • כשהמדיניות מוגדרת כ-true, הערך avoidHighways (אופציונלי) מציין שהנתיבים שחושבו צריכים להימנע מכבישים מהירים, אם אפשר.
  • כשהמדיניות הזו מוגדרת ל-true, ההגדרה avoidTolls (אופציונלי) מציינת שהנתיבים המחושבים צריכים להימנע מכבישי אגרה, אם אפשר.
  • region (אופציונלי) מציין את קוד האזור שצוין כ-ccTLD ("דומיין ברמה העליונה") בשני תווים. (למידע נוסף, ראו הטיה לפי אזור בהמשך).

הנה דוגמה ל-DirectionsRequest:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  waypoints: [
    {
      location: 'Joplin, MO',
      stopover: false
    },{
      location: 'Oklahoma City, OK',
      stopover: true
    }],
  provideRouteAlternatives: false,
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(/* now, or future date */),
    trafficModel: 'pessimistic'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

אמצעי הגעה

כשמחושבים מסלולים, צריך לציין באיזה אמצעי תחבורה להשתמש. בשלב זה, יש תמיכה באמצעי התחבורה הבאים:

  • DRIVING (ברירת מחדל) מציין מסלול נהיגה סטנדרטי באמצעות רשת הכבישים.
  • BICYCLING מבקש מסלול רכיבה על אופניים דרך שבילי אופניים ורחובות מועדפים.
  • האפליקציה TRANSIT מבקשת מסלול באמצעות מסלולי תחבורה ציבורית.
  • WALKING מבקש מסלול הליכה דרך שבילי הליכה ומדרכות.

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

הערה: ייתכן שמסלולי הליכה לא יכללו שבילים ברורים להולכי רגל, ולכן מסלולי הליכה יחזירו אזהרות בDirectionsResult. תמיד צריך להציג את האזהרות האלה למשתמש. אם לא נעשה שימוש בברירת המחדל של DirectionsRenderer, באחריותך לוודא שהאזהרות מוצגות.

אפשרויות תחבורה ציבורית

האפשרויות הזמינות לבקשת מסלול משתנות בין אמצעי הגעה. כשמבקשים לקבל מסלול לתחבורה ציבורית, המערכת מתעלמת מהאפשרויות avoidHighways, avoidTolls, waypoints[] ו-optimizeWaypoints. אפשר לציין אפשרויות ניתוב ספציפיות באמצעות ליטרל של אובייקט TransitOptions.

המסלול בתחבורה הציבורית תלוי בזמן. המסלול יוחזר רק פעם אחת בעתיד.

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

{
  arrivalTime: Date,
  departureTime: Date,
  modes[]: TransitMode,
  routingPreference: TransitRoutePreference
}

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

  • arrivalTime (אופציונלי) מציין את זמן ההגעה הרצוי כאובייקט Date. אם שעת ההגעה מצוינת, המערכת תתעלם משעת היציאה.
  • departureTime (אופציונלי) מציין את שעת היציאה הרצויה כאובייקט Date. המערכת תתעלם מ-departureTime אם צוין arrivalTime. ברירת המחדל היא עכשיו (כלומר, השעה הנוכחית) אם לא צוין ערך עבור departureTime או של arrivalTime.
  • modes[] (אופציונלי) הוא מערך שמכיל לפחות ליטר אחד של אובייקט TransitMode. אפשר לכלול את השדה הזה רק אם הבקשה כוללת מפתח API. כל TransitMode מציין אמצעי תחבורה מועדף. מותר להשתמש בערכים הבאים:
    • לפי BUS, המסלול המחושב אמור להעדיף נסיעה באוטובוס.
    • לפי המדד RAIL, המסלול המחושב אמור להיות מועדף לנסיעה ברכבת, בחשמלית, ברכבת קלה וברכבת תחתית.
    • לפי SUBWAY, המסלול המחושב צריך להעדיף נסיעה ברכבת תחתית.
    • לפי TRAIN, המסלול המחושב אמור להעדיף נסיעה ברכבת.
    • לפי TRAM, המסלול המחושב אמור להיות מועדף לנסיעה ברכבת קלה וברכבת קלה.
  • ההגדרה routingPreference (אופציונלי) מציינת העדפות עבור נתיבי תחבורה ציבורית. כשבוחרים באפשרות הזו, ניתן להטות את האפשרויות שמוחזרות על ידי המערכת, במקום לאשר את נתיב ברירת המחדל הטוב ביותר שנבחר על ידי ה-API. יש לציין את השדה הזה רק אם הבקשה כוללת מפתח API. מותר להשתמש בערכים הבאים:
    • FEWER_TRANSFERS מציין שהמסלול המחושב צריך להעדיף מספר מוגבל של העברות.
    • LESS_WALKING מציין שהמסלול המחושב צריך להעדיף כמויות מוגבלות של הליכה.

למטה מופיעה דוגמה של DirectionsRequest בתחבורה ציבורית:

{
  origin: 'Hoboken NJ',
  destination: 'Carroll Gardens, Brooklyn',
  travelMode: 'TRANSIT',
  transitOptions: {
    departureTime: new Date(1337675679473),
    modes: ['BUS'],
    routingPreference: 'FEWER_TRANSFERS'
  },
  unitSystem: google.maps.UnitSystem.IMPERIAL
}

אפשרויות נהיגה

אפשר לציין אפשרויות מסלול למסלול באמצעות האובייקט DrivingOptions.

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

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

  • departureTime (חובה בליטרל של drivingOptions כדי להיות חוקי) מציין את שעת היציאה הרצויה כאובייקט Date. הערך צריך להיות מוגדר לשעה הנוכחית או בזמן כלשהו בעתיד. התאריך לא יכול להיות בעבר. (ה-API ממיר את כל התאריכים ל-UTC כדי להבטיח טיפול עקבי באזורי זמן שונים.) ללקוחות של הפלטפורמה המתקדמת של מפות Google, אם כוללים את departureTime בבקשה, ה-API יחזיר את המסלול הטוב ביותר בהתאם לתנאי התנועה הצפויים באותו זמן, וכן את הזמן הצפוי בתנועה (duration_in_traffic). אם לא ציינת שעת יציאה (כלומר, אם הבקשה לא כוללת את drivingOptions), המסלול שמוחזר הוא לרוב המסלול הטוב ביותר, בלי להביא בחשבון את מצב התנועה.
  • trafficModel (אופציונלי) מציין את ההנחות שישמשו לחישוב זמן התנועה. ההגדרה הזו משפיעה על הערך המוחזר בשדה duration_in_traffic בתגובה, שמכיל את הזמן החזוי בתנועה על סמך ממוצעים היסטוריים. ברירת המחדל היא bestguess. מותר להשתמש בערכים הבאים:
    • המדד bestguess (ברירת מחדל) מציין שה-duration_in_traffic שמוחזר צריך להיות ההערכה הטובה ביותר לגבי זמן הנסיעה, על סמך מה שידוע גם על מצב התנועה וגם על מצב התנועה בזמן אמת. עומס התנועה בשידור חי הולך וגדל ככל שdepartureTime קרוב יותר עכשיו.
    • לפי המדד pessimistic, המאפיין duration_in_traffic המוחזר צריך להיות ארוך יותר מזמן הנסיעה בפועל ברוב הימים, אבל לפעמים ימים עם תנאי תנועה גרועים במיוחד עשויים לחרוג מהערך הזה.
    • לפי המדד optimistic, ההחזר על duration_in_traffic יהיה קצר יותר ממשך הנסיעה בפועל ברוב הימים, אבל מדי פעם הימים עם תנאי תנועה טובים במיוחד עשויים להיות מהירים יותר מהערך הזה.

הנה דוגמה של DirectionsRequest למסלול נסיעה:

{
  origin: 'Chicago, IL',
  destination: 'Los Angeles, CA',
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

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

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

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

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

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

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

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

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

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

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

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

דוגמה

אובייקט הכיוונים

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

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

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

מסלולים

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

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

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

  • legs[] מכיל מערך של DirectionsLeg אובייקטים, שכל אחד מהם מכיל מידע על רגל של המסלול, משני מיקומים בתוך הנתיב הנתון. תקיים רגל נפרדת לכל ציון דרך או יעד. (נתיב ללא ציוני דרך יכיל DirectionsLeg בדיוק). כל רגל מכילה סדרה של DirectionStep.
  • waypoint_order מכיל מערך שמציין את הסדר של כל ציוני הדרך במסלול המחושב. המערך הזה עשוי להכיל סדר שינויים אם DirectionsRequest הועבר optimizeWaypoints: true.
  • overview_path מכיל מערך של LatLng שמייצג נתיב משוער (חלקי) של המסלול שמתקבל.
  • overview_polyline מכיל אובייקט points יחיד שמכיל ייצוג מקודד ומפוצל של המסלול. קו מרובה השורות הוא נתיב משוער (חלקי) של המסלול שנוצר.
  • bounds מכיל LatLngBounds שמציין את גבולות המצולע לאורך המסלול הנתון.
  • copyrights מכיל את הטקסט של זכויות היוצרים להצגה במסלול הזה.
  • warnings[] מכיל מערך של אזהרות שיוצגו כאשר המסלול הזה יוצג. אם לא משתמשים באובייקט DirectionsRenderer שסופק, יש לטפל באזהרות האלה ולהציג אותן בעצמך.
  • מחיר הכרטיס הכולל: fare (כלומר, סך עלויות הכרטיסים) במסלול הזה. הנכס הזה מוחזר רק לבקשות תחבורה ציבורית ורק למסלולים שבהם מידע על כרטיסים זמין לכל חברות התחבורה הציבורית. המידע כולל:
    • 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 מהמקור של החלק הזה. מכיוון ששירות המסלול באינטרנט מחשב את המסלול בין מיקומים באמצעות אפשרות התחבורה הקרובה ביותר (בדרך כלל כביש) בנקודת ההתחלה ונקודת הסיום, ייתכן ש-start_location יהיה שונה מהמקור שסופק על המסלול הזה, אם כביש כלשהו לא נמצא ליד המקור.
  • end_location מכיל את LatLng של היעד של החלק הזה. מכיוון ש-DirectionsService מחשב מסלול בין מיקומים על ידי שימוש באפשרות התחבורה הקרובה ביותר (בדרך כלל כביש) בנקודות ההתחלה והסיום, ייתכן ש-end_location יהיה שונה מהיעד שסופק לקטע הזה, אם כביש מסוים לא קרוב ליעד.
  • השדה start_address מכיל את הכתובת שקריאים לבני אדם (בדרך כלל כתובת פיזית) של תחילת הקטע הזה.

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

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

הוראות הגעה

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

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

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

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

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

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

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

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

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

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

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

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

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

  • ב-url מופיעה כתובת URL לקו התחבורה הציבורית הזה, כפי שסופק על ידי חברת התחבורה הציבורית.
  • icon מכיל כתובת URL לסמל שמשויך לשורה הזו. ברוב הערים נעשה שימוש בסמלים כלליים שמשתנים לפי סוג הרכב. לקווים מסוימים של תחבורה ציבורית, כמו מערכת הרכבת התחתית של ניו יורק, יש סמלים ספציפיים לקו הזה.
  • color מכיל את הצבע הנפוץ של שילוט בתחבורה הציבורית הזו. הצבע יצוין כמחרוזת הקסדצימלית, כגון: #FF0033.
  • text_color מכיל את צבע הטקסט שמשמש בדרך כלל לשילוט של הקו הזה. הצבע יצוין כמחרוזת הקסדצימלית.
  • vehicle מכיל אובייקט Vehicle שכולל את המאפיינים הבאים:
    • name מכיל את שם הרכב בשורה הזו. למשל "רכבת תחתית".
    • 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>

דוגמה

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

כפי שמצוין במסלול הבקשות, אפשר גם לציין ציוני דרך (מסוג 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

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

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

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

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

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

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

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

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

TypeScript

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

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

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

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

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

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

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

  if (!myroute) {
    return;
  }

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

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

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

לדגימה