דף זה תורגם על ידי Cloud Translation API.

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

הערה: ספריות בצד השרת

סקירה כללית

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

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

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

תחילת העבודה

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

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

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

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

תמחור

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

מדיניות

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

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

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

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

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

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

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

השדה origin (חובה) מציין את מיקום ההתחלה שממנו יש לחשב את המסלול. אפשר לציין את הערך הזה בתור String (לדוגמה, "שיקגו, ישראל"), כערך של LatLng או כאובייקט מקום. אם משתמשים באובייקט Place, אפשר לציין מזהה מקום, מחרוזת שאילתה או מיקום LatLng. אפשר לאחזר מזהי מקומות משירותי הקידוד הגיאוגרפי, חיפוש מקומות והשלמה אוטומטית של מקומות, ב-API של JavaScript ב-Maps. לדוגמה, השימוש במזהי מקומות מההשלמה האוטומטית של מקומות זמין במאמר השלמה אוטומטית של מקומות ומסלולים.
השדה destination (חובה) מציין את מיקום הסיום שאליו יש לחשב את המסלול. האפשרויות זהות לשדה origin שמתואר למעלה.
travelMode (חובה) מציין את אמצעי התחבורה שבו יש להשתמש בחישוב המסלול. הערכים החוקיים מפורטים במצבי נסיעה בהמשך.
השדה transitOptions (אופציונלי) מציין ערכים שחלים רק על בקשות שבהן travelMode הוא TRANSIT. ערכים חוקיים מתוארים בהמשך בקטע אפשרויות תחבורה ציבורית.
השדה drivingOptions (אופציונלי) מציין ערכים שחלים רק על בקשות שבהן travelMode הוא DRIVING. הערכים החוקיים מתוארים בקטע אפשרויות נהיגה בהמשך.
השדה unitSystem (אופציונלי) מציין באיזו מערכת להשתמש כדי להציג תוצאות. הערכים התקינים מצוינים ב-System Systems בהמשך.
waypoints[] (אופציונלי) מציין מערך של DirectionsWaypoint. ציוני הדרך משנים נתיב על ידי ניתובו דרך המיקומים שצוינו. ציון דרך מצוין כליטרל של אובייקט עם השדות הבאים:
- location מציין את המיקום של ציון הדרך, כ-LatLng, כאובייקט Place או כ-String שהקידוד שלו יעבור קידוד.
- הערך stopover הוא בוליאני ומציין שנקודת הציון היא עצירה במסלול, מה שגורם לפיצול המסלול לשני מסלולים.
(למידע נוסף על ציוני דרך בנתיבים בהמשך).
הפונקציה optimizeWaypoints (אופציונלי) מציינת שייתכן שהמסלול שנעשה בו שימוש ב-waypoints שסופק עבר אופטימיזציה, על ידי סידור מחדש של ציוני הדרך לפי סדר יעיל יותר. אם true, שירות ההזמנות יחזיר את waypoints שהוזמן מחדש בשדה waypoint_order.(למידע נוסף, ניתן לעיין למטה בקטע שימוש בציוני דרך בנתיבים).
ההגדרה provideRouteAlternatives (אופציונלי) כאשר היא מוגדרת כ-true מציינת ששירות המסלולים עשוי לספק יותר מחלופה אחת של נתיב בתגובה. חשוב לשים לב שחלופה חלופית של המסלול עשויה להאריך את זמן התגובה מהשרת. אפשרות זו זמינה רק לבקשות ללא ציוני דרך בינוניים.
כשמגדירים את הערך avoidFerries (אופציונלי) בשדה true, צריך לציין שהמסלולים שמחושבים יימנעו ממעבורות, אם הדבר אפשרי.
אם מגדירים את הערך avoidHighways (אופציונלי), מגדירים את המסלול שבנתיב true, כדי להימנע מכבישים מהירים אם אפשר.
כשמגדירים את הערך avoidTolls (אופציונלי), המערכת מגדירה את true לפיו, כדי להימנע מכבישי אגרה אם זה אפשרי.
השדה region (אופציונלי) מציין את קוד האזור שמצוין כ-ccTLD ("דומיין ברמה העליונה") עם שני תווים. (למידע נוסף, ניתן לעיין בקטע הטיית אזורים בהמשך).

הערה: השדה durationInTraffic לא בשימוש. בעבר, הדרך המומלצת ללקוחות בתוכנית הפרימיום של מפות Google לציין אם התוצאה אמורה לכלול משך זמן שמתחשב בתנאי התנועה הנוכחיים. במקומה יש להשתמש בשדה drivingOptions.

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

דוגמת DirectionsRequest בתחבורה ציבורית מוצגת כאן:

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

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

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

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

{
  departureTime: Date,
  trafficModel: TrafficModel
}

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

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

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

הדוגמה הבאה היא DirectionsRequest כדי לקבל מסלול נסיעה:

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

יחידות יחידה

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

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

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

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

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

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

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

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

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

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

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

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

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

בגוף ה-HTML:

<div>
<strong>Start: </strong>
<select id="start" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
  <option value="chicago, il">Chicago</option>
  <option value="st louis, mo">St Louis</option>
  <option value="joplin, mo">Joplin, MO</option>
  <option value="oklahoma city, ok">Oklahoma City</option>
  <option value="amarillo, tx">Amarillo</option>
  <option value="gallup, nm">Gallup, NM</option>
  <option value="flagstaff, az">Flagstaff, AZ</option>
  <option value="winona, az">Winona</option>
  <option value="kingman, az">Kingman</option>
  <option value="barstow, ca">Barstow</option>
  <option value="san bernardino, ca">San Bernardino</option>
  <option value="los angeles, ca">Los Angeles</option>
</select>
</div>

דוגמה

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

function initMap() {
  var directionsService = new google.maps.DirectionsService();
  var directionsRenderer = new google.maps.DirectionsRenderer();
  var haight = new google.maps.LatLng(37.7699298, -122.4469157);
  var oceanBeach = new google.maps.LatLng(37.7683909618184, -122.51089453697205);
  var mapOptions = {
    zoom: 14,
    center: haight
  }
  var map = new google.maps.Map(document.getElementById('map'), mapOptions);
  directionsRenderer.setMap(map);
}

function calcRoute() {
  var selectedMode = document.getElementById('mode').value;
  var request = {
      origin: haight,
      destination: oceanBeach,
      // Note that JavaScript allows us to access the constant
      // using square brackets and a string value as its
      // "property."
      travelMode: google.maps.TravelMode[selectedMode]
  };
  directionsService.route(request, function(response, status) {
    if (status == 'OK') {
      directionsRenderer.setDirections(response);
    }
  });
}

בגוף ה-HTML:

<div>
<strong>Mode of Travel: </strong>
<select id="mode" onchange="calcRoute();">
  <option value="DRIVING">Driving</option>
  <option value="WALKING">Walking</option>
  <option value="BICYCLING">Bicycling</option>
  <option value="TRANSIT">Transit</option>
</select>
</div>

דוגמה

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

יוצגו הוראות טקסט באמצעות הגדרת השפה המועדפת של הדפדפן, או השפה שצוינה בזמן טעינת ה-API של JavaScript באמצעות הפרמטר language. (מידע נוסף זמין במאמר התאמה לשוק המקומי.) במקרה של מסלול תחבורה ציבורית, השעה תוצג באזור הזמן של התחנה.

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

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

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

בגוף ה-HTML:

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

דוגמה

האובייקט ResultResults

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

מסלולים לקבלת מסלול

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

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

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

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

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

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

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

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

steps[] מכיל מערך של DirectionsStep אובייקטים שמציין מידע על כל שלב בנפרד של התהליך.
distance מציין את המרחק הכולל המכוס בטביעת הרגל הזו כאובייקט Distance בצורה הבאה:
- המרחק שצוין במטרים הוא value
- text מכיל ייצוג מחרוזת של המרחק, שמוגדר כברירת מחדל ביחידות ששימשו כמקור. (לדוגמה, מיילים ישמשו לכל מקור בארה"ב). אפשר לשנות את המערכת הזו על ידי הגדרה ספציפית של UnitSystem בשאילתה המקורית. חשוב לשים לב שלא משנה באיזו מערכת יחידות השתמשת, השדה distance.value תמיד מכיל ערך שמצוין במטרים.
אם המרחק לא ידוע, ייתכן שהשדות האלו לא מוגדרים.
duration מציין את משך הזמן הכולל של הקטע הזה בתור אובייקט Duration בצורה הבאה:
- value מציין את משך הזמן בשניות.
- text מכיל ייצוג מחרוזת של משך הזמן.
ייתכן שהשדות האלו לא יוגדרו אם משך הזמן לא ידוע.
duration_in_traffic מציין את משך הזמן הכולל של הקטע הזה, תוך התחשבות במצב התנועה הנוכחי. הפונקציה duration_in_traffic מוחזרת רק אם מתקיימים כל התנאים הבאים:
- הבקשה לא כוללת ציוני דרך של עצירות ביניים. כלומר, הוא לא כולל ציוני דרך שבהם stopover הוא true.
- הבקשה היא ספציפית למסלול נסיעה – הערך mode מוגדר ל-driving.
- הערך departureTime נכלל כחלק מהשדה drivingOptions בבקשה.
- תנאי התנועה זמינים עבור המסלול המבוקש.
השדה duration_in_traffic מכיל את השדות הבאים:
- value מציין את משך הזמן בשניות.
- text מכיל ייצוג קריא לבני אדם.
הערך arrival_time מכיל את זמן ההגעה המשוער לקטע הזה. הנכס הזה מוחזר רק למסלולי תחבורה ציבורית. התוצאה מוחזרת כאובייקט Time עם שלושה מאפיינים:
- value הזמן שצוין כאובייקט JavaScript Date.
- text הזמן שצוין כמחרוזת. השעה מוצגת באזור הזמן של תחנת התחבורה הציבורית.
- השדה time_zone מכיל את אזור הזמן של התחנה הזו. הערך הוא השם של אזור הזמן כפי שמוגדר במסד הנתונים של אזור הזמן IANA, למשל "America/New_York".
departure_time מכיל את זמן היציאה המשוער של הרגל הזו, שצוין כאובייקט Time. departure_time זמין רק למסלול בתחבורה ציבורית.
start_location מכיל את LatLng מהמקור של הרגל הזה. מכיוון ששירות האינטרנט של מסלולי ההגעה מחשב מסלול בין מיקומים על ידי שימוש באפשרות התחבורה הקרובה ביותר (בדרך כלל דרך) לנקודות ההתחלה והסיום, ייתכן ש-start_location יהיה שונה מהמקור שסופק לתנועה הזו אם, לדוגמה, הדרך לא נמצאת ליד המקור.
end_location מכיל את LatLng של היעד של הרגל הזו. מכיוון שב-DirectionsService מחושב מסלול בין מיקומים על ידי שימוש באמצעי התחבורה הקרוב ביותר (בדרך כלל כביש) בנקודות ההתחלה והסיום, ייתכן ש-end_location יהיה שונה מהיעד שהוגדר לתנועה הזו אם, לדוגמה, אין כביש שנמצא קרוב ליעד.
start_address מכיל את הכתובת הגלויה לבני אדם (בדרך כלל כתובת רחוב) מתחילת קטע זה.

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

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

הוראות הגעה

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

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

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

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

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

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

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

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

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

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

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

name מכיל את השם המלא של קו התחבורה הציבורית הזה. לדוגמה: "7 Avenue Express" או "14th St Crossland".
short_name מכיל את השם המקוצר של קו התחבורה הציבורית הזה. בדרך כלל המספר הזה יהיה מספר, למשל "2" או "M14".
agencies הוא מערך שמכיל אובייקט TransitAgency אחד. האובייקט TransitAgency מספק מידע לגבי המפעיל של הקו הזה, כולל המאפיינים הבאים:
- name מכיל את השם של חברת התחבורה הציבורית.
- phone מכיל את מספר הטלפון של חברת התחבורה הציבורית.
- url מכיל את כתובת ה-URL של חברת התחבורה הציבורית.
הערה: אם אתם מעבדים באופן ידני מסלול תחבורה ציבורית במקום להשתמש באובייקט DirectionsRenderer, עליכם להציג את השמות וכתובות ה-URL של חברות התחבורה הציבורית שמשרתות את תוצאות הנסיעה.
url מכיל כתובת URL לקו התחבורה הציבורית הזה, כפי שסופק על ידי חברת התחבורה הציבורית.
icon מכיל כתובת URL עבור הסמל המשויך לשורה זו. ברוב הערים יש סמלים כלליים שמשתנים לפי סוג הרכב. לקווים מסוימים של תחבורה ציבורית, כמו מערכת הרכבת התחתית בניו יורק, יש סמלים ספציפיים לקו הזה.
color מכיל את הצבע המקובל לשילוט הזה. הצבע יצוין כמחרוזת הקסדצימלית, למשל: #FF0033.
text_color מכיל את צבע הטקסט שמשמש בדרך כלל לשילוט של הקו הזה. הצבע יצוין כמחרוזת הקסדצימלית.
vehicle מכיל אובייקט Vehicle שכולל את המאפיינים הבאים:
- name מכיל את שם הרכב בשורה הזו. למשל "Subway"
- type מכיל את סוג הרכב שמשמש בקו הזה. במסמכי התיעוד בנושא סוג הרכב יש רשימה מלאה של ערכים נתמכים.
- בעמודה icon יש כתובת URL של הסמל שמשויך בדרך כלל לסוג הרכב הזה.
- בכתובת local_icon מצוינת כתובת ה-URL של הסמל שמשויך לסוג הרכב הזה, על סמך השילוט המקומי.

סוג הרכב

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

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

בדיקת תוצאות מסלול

הרכיבים של DirectionsResults – 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 כברירת מחדל.

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

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

דוגמה

לדגום

Stackblitch.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell