סקירה כללית
אפשר לחשב מסלולים (באמצעות מגוון שיטות של תחבורה) באמצעות האובייקט DirectionsService
. האובייקט הזה מתקשר עם שירות המסלולים של Google Maps API, שמקבל בקשות למסלולים ומחזיר נתיב יעיל.
זמן הנסיעה הוא הגורם העיקרי שאנחנו מבצעים אופטימיזציה שלו, אבל יכול להיות שנביא בחשבון גם גורמים אחרים כמו מרחק, מספר הפניות ועוד.
אתם יכולים לטפל בתוצאות ההנחיות האלה בעצמכם או להשתמש באובייקט DirectionsRenderer
כדי להציג את התוצאות האלה.
כשמציינים את נקודת המוצא או היעד בבקשה לקבלת מסלול, אפשר לציין מחרוזת שאילתה (לדוגמה, 'תל אביב, תל אביב-יפו' או 'Darwin, NSW, Australia'), ערך LatLng
או אובייקט Place.
שירות המסלולים יכול להחזיר מסלולים שמחולקים למספר חלקים באמצעות סדרה של נקודות ציון. המסלול מוצג כקו פוליגון שמשרטט את המסלול במפה, או כסדרה של תיאורים טקסטואליים בתוך רכיב <div>
(לדוגמה, "פנייה ימינה לרמפה של גשר וויליאמסבורג").
תחילת העבודה
לפני שמשתמשים בשירות המסלולים ב-Maps JavaScript API, צריך לוודא ש-Directions API מופעל במסוף Google Cloud, באותו פרויקט שהגדרתם ל-Maps JavaScript API.
כדי להציג את רשימת ממשקי ה-API המופעלים:
- נכנסים ל מסוף Google Cloud.
- לוחצים על הלחצן Select a project, בוחרים את אותו פרויקט שהגדרתם ל-Maps JavaScript API ולוחצים על Open.
- ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Directions API.
- אם ה-API מופיע ברשימה, סימן שהכול מוכן. אם ה-API לא מופיע ברשימה, מפעילים אותו:
- בחלק העליון של הדף, בוחרים באפשרות ENABLE API כדי להציג את הכרטיסייה Library. לחלופין, בתפריט הימני, לוחצים על ספרייה.
- מחפשים את Directions API ובוחרים בו מרשימת התוצאות.
- לוחצים על הפעלה. בסיום התהליך, Directions API יופיע ברשימת ממשקי ה-API במרכז הבקרה.
תמחור ומדיניות
תמחור
החל מ-16 ביולי 2018, תוכנית תמחור חדשה של תשלום לפי שימוש נכנסה לתוקף במפות Google, במסלולים ובמקומות. למידע נוסף על התמחור והמגבלות החדשות לשימוש בשירות 'מסלול הגעה' ב-JavaScript, קראו את המאמר שימוש וחיובים בנושא Directions API.
מדיניות
השימוש בשירות 'מסלולי הגעה' חייב להתבצע בהתאם למדיניות שמפורטת עבור Directions API.
בקשות לקבלת מסלול
הגישה לשירות ההנחיות היא אסינכרונית, כי Google Maps API צריך לבצע קריאה לשרת חיצוני. לכן, צריך להעביר method של קריאה חוזרת שיתבצע בסיום הבקשה. שיטת הקריאה החוזרת הזו אמורה לעבד את התוצאות. הערה: שירות המסלולים עשוי להחזיר יותר ממסלול אפשרי אחד כמערך של routes[]
נפרדים.
כדי להשתמש בהוראות הגעה בממשק API של JavaScript במפות Google, יוצרים אובייקט מסוג 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
. אפשר לאחזר מזהי מקומות מהשירותים של המרת כתובות לקואורדינטות (geocoding), חיפוש מקומות והשלמה אוטומטית למקומות ב-Maps JavaScript API. דוגמה לשימוש במזהי מקומות מההשלמה האוטומטית למקומות מפורטת במאמר השלמה אוטומטית למקומות ומסלול הגעה.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
, המערכת תנסה להימנע ממעבורות במסלולים המחושבים, אם אפשר.avoidHighways
(אופציונלי) כשהערך שלו מוגדר כ-true
, המערכת תנסה להימנע מכבישים מהירים ראשיים במסלולים שתחשב, אם אפשר.avoidTolls
(אופציונלי) כשהערך שלו מוגדר כ-true
, המערכת תנסה להימנע מכבישי אגרה במסלולים המחושבים, אם אפשר.region
(אופציונלי) מציין את קוד האזור, שמצוין כערך בן שני תווים של דומיין ברמה עליונה עם קוד מדינה (ccTLD). (למידע נוסף, ראו הטיה לאזור בהמשך).
לפניכם דוגמה ל-DirectionsRequest
:
{ origin: 'Chicago, IL', destination: 'Los Angeles, CA', waypoints: [ { location: 'Joplin, MO', stopover: false },{ location: 'Oklahoma City, OK', stopover: true }], provideRouteAlternatives: false, travelMode: 'DRIVING', drivingOptions: { departureTime: new Date(/* now, or future date */), trafficModel: 'pessimistic' }, unitSystem: google.maps.UnitSystem.IMPERIAL }
אמצעי הגעה
כשמחשבים מסלול, צריך לציין את אמצעי התחבורה שבו רוצים להשתמש. בשלב הזה יש תמיכה באפשרויות הנסיעה הבאות:
DRIVING
(ברירת המחדל) מציינת מסלול נסיעה רגיל באמצעות רשת הכבישים.BICYCLING
מבקש מסלול רכיבה על אופניים דרך שבילי אופניים ורחובות מועדפים.TRANSIT
מבקשת מסלול דרך מסלולי תחבורה ציבורית.WALKING
מבקשת מסלול הליכה דרך שבילים להולכי רגל ומדרכות.
כדי לבדוק עד כמה יש תמיכה במסלולים במדינה מסוימת, אפשר לעיין בפרטי הכיסוי של פלטפורמת מפות Google. אם מבקשים מסלול לאזור שבו סוג המסלול הזה לא זמין, התגובה תכלול את הערך DirectionsStatus
="ZERO_RESULTS
".
הערה: יכול להיות שמסלולי הליכה לא יכללו דרכים ברורות להולכי רגל, ולכן מסלולי הליכה יחזירו אזהרות ב-DirectionsResult
. האזהרות האלה חייבות להופיע תמיד למשתמשים. אם לא משתמשים ב-DirectionsRenderer
שמוגדר כברירת מחדל, אתם אחראים לוודא שהאזהרות יוצגו.
אפשרויות תחבורה ציבורית
האפשרויות הזמינות לבקשת מסלול משתנות בהתאם לאמצעי התחבורה.
כשמבקשים מסלול לתחבורה ציבורית, המערכת תתעלם מהאפשרויות avoidHighways
, avoidTolls
, waypoints[]
ו-optimizeWaypoints
. אפשר לציין אפשרויות ניתוב ספציפיות לתחבורה ציבורית באמצעות המשתנה המילולי של האובייקט TransitOptions
.
מסלולי תחבורה ציבורית הם תלויי זמן. ההנחיות יוצגו רק לזמנים עתידיים.
המשתנה המילולי של האובייקט TransitOptions
מכיל את השדות הבאים:
{ arrivalTime: Date, departureTime: Date, modes[]: TransitMode, routingPreference: TransitRoutePreference }
השדות האלה מוסברים בהמשך:
arrivalTime
(אופציונלי) מציין את זמן ההגעה הרצוי כאובייקטDate
. אם צוינה שעת הגעה, המערכת מתעלמת משעת היציאה.departureTime
(אופציונלי) מציין את זמן היציאה הרצוי כאובייקטDate
. המערכת תתעלם מ-departureTime
אם צויןarrivalTime
. אם לא צוין ערך בשדהdepartureTime
או בשדהarrivalTime
, ערך ברירת המחדל הוא 'עכשיו' (כלומר, השעה הנוכחית).modes[]
(אופציונלי) הוא מערך שמכיל לפחות לישן אחד של אובייקטTransitMode
. אפשר לכלול את השדה הזה רק אם הבקשה כוללת מפתח API. כלTransitMode
מציין אמצעי תחבורה מועדף. הערכים הבאים מותרים:- הערך
BUS
מציין שהמסלול המחושב צריך לתת עדיפות לנסיעה באוטובוס. RAIL
מציין שהמסלול המחושב צריך לתת עדיפות לנסיעה ברכבת, בחשמלית, ברכבת קלה וברכבת תחתית.SUBWAY
מציין שהמסלול המחושב צריך לתת עדיפות לנסיעה ברכבת תחתית.TRAIN
מציין שצריך לתת עדיפות לנסיעה ברכבת במסלול המחושב.- הערך
TRAM
מציין שהמסלול המחושב צריך לתת עדיפות לנסיעה בחשמלית וברכבת קלה.
- הערך
routingPreference
(אופציונלי) מציין את ההעדפות למסלולי תחבורה ציבורית. באמצעות האפשרות הזו אפשר להטות את האפשרויות שיוחזרו, במקום לקבל את הנתיב הטוב ביותר שמוגדר כברירת מחדל על ידי ה-API. אפשר לציין את השדה הזה רק אם הבקשה כוללת מפתח API. הערכים הבאים מותרים:FEWER_TRANSFERS
מציין שהמסלול המחושב צריך להעדיף מספר מוגבל של החלפות.LESS_WALKING
מציין שהמסלול המחושב צריך להעדיף כמויות מוגבלות של הליכה.
דוגמה ל-DirectionsRequest
בתחבורה ציבורית מוצגת בהמשך:
{ origin: 'Hoboken NJ', destination: 'Carroll Gardens, Brooklyn', travelMode: 'TRANSIT', transitOptions: { departureTime: new Date(1337675679473), modes: ['BUS'], routingPreference: 'FEWER_TRANSFERS' }, unitSystem: google.maps.UnitSystem.IMPERIAL }
אפשרויות נהיגה
אפשר לציין אפשרויות ניתוב למסלול נסיעה באמצעות האובייקט DrivingOptions
.
אובייקט DrivingOptions
מכיל את השדות הבאים:
{ departureTime: Date, trafficModel: TrafficModel }
השדות האלה מוסברים בהמשך:
departureTime
(נדרש כדי שהליטרל של האובייקטdrivingOptions
יהיה תקף) מציין את זמן היציאה הרצוי כאובייקטDate
. הערך צריך להיות מוגדר לשעה הנוכחית או למועד כלשהו בעתיד. הוא לא יכול להיות בעבר. (ה-API ממיר את כל התאריכים ל-UTC כדי להבטיח טיפול עקבי באזורי זמן שונים). לקוחות עם תוכנית 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
אמור להיות קצר יותר מזמני הנסיעה בפועל ברוב הימים, אבל בימים מסוימים שבהם תנאי התנועה טובים במיוחד, ייתכן שהנסיעה תהיה מהירה יותר מהערך הזה.
- הערך
בהמשך מופיעה דוגמה לקובץ 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' } }
מערכות יחידות
כברירת מחדל, המסלול מחושב ומוצג לפי מערכת היחידות של המדינה או האזור שמהם מתחיל המסלול.
(הערה: מקורות שמתוארים באמצעות קואורדינטות של קו אורך/קו רוחב במקום כתובות תמיד מוגדרים כברירת מחדל ליחידות מטריות). לדוגמה, במסלול מ-Chicago, IL אל Toronto, ONT התוצאות יוצגו במיילים, ובמסלול ההפוך התוצאות יוצגו בקילומטרים. אפשר לשנות את מערכת היחידות הזו על ידי הגדרה מפורשת של מערכת יחידות בבקשה, באמצעות אחד מהערכים הבאים של UnitSystem
:
UnitSystem.METRIC
מציין שימוש במערכת המטרית. המרחקים מוצגים בקילומטרים.UnitSystem.IMPERIAL
מציין שימוש במערכת האימפריה (אנגלית). המרחקים מוצגים במיילים.
הערה: ההגדרה הזו של מערכת היחידות משפיעה רק על הטקסט שמוצג למשתמש. תוצאת המסלול מכילה גם ערכים של המרחק, שלא מוצגים למשתמש, ותמיד הם בביטוי במטרים.
הטיה לפי אזור בהוראות הגעה
שירות המסלולים של Google Maps API מחזיר תוצאות של כתובות שמושפעות מהדומיין (אזור או מדינה) שממנו העליתם את ה-bootstrap של JavaScript. (מכיוון שרוב המשתמשים טוענים את https://maps.googleapis.com/
, המערכת מגדירה דומיין משתמע לארצות הברית). אם תטעינו את ה-bootstrap מדומיין נתמך אחר, התוצאות יהיו מושפעות מהדומיין הזה. לדוגמה, חיפושים של 'תל אביב' עשויים להניב תוצאות שונות באפליקציות שנטענות ב-https://maps.googleapis.com/
(ארצות הברית) מאשר באפליקציה שנטענת ב-http://maps.google.es/
(ספרד).
אפשר גם להגדיר את שירות המסלול כך שיחזיר תוצאות שמתמקדות באזור מסוים באמצעות הפרמטר region
. הפרמטר הזה מקבל קוד אזור, שמצוין בתג משנה של אזור ב-Unicode בן שני תווים (לא מספריים). ברוב המקרים, התגים האלה ממופים ישירות לערכים של שני תווים של דומיינים ברמה עליונה עם קוד מדינה (ccTLD), כמו 'uk' ב-'co.uk', לדוגמה. במקרים מסוימים, התג region
תומך גם בקודים של ISO-3166-1, שלפעמים שונים מהערכים של ccTLD (לדוגמה, 'GB' עבור 'בריטניה הגדולה').
כשמשתמשים בפרמטר region
:
- יש לציין רק מדינה או אזור אחד. המערכת מתעלמת מכמה ערכים, ויכול להיות שהדבר יוביל לבקשה שנכשלה.
- יש להשתמש רק בתגי משנה של אזורים עם שני תווים (בפורמט Unicode CLDR). כל קלט אחר יגרום לשגיאות.
אפשר להשתמש בהטיה לפי אזור רק במדינות ובאזורים שבהם יש תמיכה בהנחיות. בפרטי הכיסוי של הפלטפורמה של מפות Google תוכלו לראות את הכיסוי הבינלאומי של Directions API.
הוראות לעיבוד
כדי להתחיל בקשת מסלול ל-DirectionsService
באמצעות השיטה route()
, צריך להעביר קריאה חוזרת (callback) שתתבצע בסיום בקשת השירות. קוד ה-callback הזה יחזיר בתגובה את הערכים DirectionsResult
ו-DirectionsStatus
.
סטטוס השאילתה לקבלת מסלול
הפונקציה DirectionsStatus
עשויה להחזיר את הערכים הבאים:
OK
מציין שהתגובה מכילהDirectionsResult
תקין.- הערך
NOT_FOUND
מציין שלא ניתן היה לבצע גיאוקוד של לפחות אחד מהמיקומים שצוינו במקור, ביעד או בנקודות העצירה בבקשה. - הערך
ZERO_RESULTS
מציין שלא נמצא מסלול בין נקודת היציאה ליעד. - הערך
MAX_WAYPOINTS_EXCEEDED
מציין שסופקו יותר מדי שדותDirectionsWaypoint
ב-DirectionsRequest
. מגבלות על נקודות דרך - הערך
MAX_ROUTE_LENGTH_EXCEEDED
מציין שהמסלול המבוקש ארוך מדי ואי אפשר לעבד אותו. השגיאה הזו מתרחשת כשמתקבלות הוראות מורכבות יותר. כדאי לנסות לצמצם את מספר נקודות הדרך, הפניות או ההוראות. INVALID_REQUEST
מציין שה-DirectionsRequest
שסופק לא תקף. הסיבות הנפוצות ביותר לקוד השגיאה הזה הן בקשות שבהן חסר מקור או יעד, או בקשה לתחבורה ציבורית שכוללת נקודות עצירה.- הערך
OVER_QUERY_LIMIT
מציין שדף האינטרנט שלח יותר מדי בקשות בפרק הזמן המורשה. - הערך
REQUEST_DENIED
מציין שלדף האינטרנט אין הרשאה להשתמש בשירות הניווט. UNKNOWN_ERROR
מציין שלא ניתן היה לעבד בקשה לקבלת מסלול בגלל שגיאה בשרת. יכול להיות שהבקשה תאושר אם תנסה שוב.
לפני עיבוד התוצאה, צריך לוודא שהשאילתה לקבלת מסלול החזירה תוצאות תקינות על ידי בדיקת הערך הזה.
הצגת DirectionsResult
המאפיין 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>
בדוגמה הבאה מוצגות מסלולים באמצעי תחבורה שונים בין Haight-Ashbury ל-Ocean Beach בסן פרנסיסקו, קליפורניה:
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>
האובייקט DirectionsResult
כששולחים בקשה לקבלת מסלול ל-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"
מציין שהפעלת ה-geocode הסתיימה בהצלחה, אבל לא הוחזרו תוצאות. מצב כזה יכול לקרות אם הועברו למקודם הגיאוגרפית נתוניaddress
לא קיימים.
- הערך
-
הערך
partial_match
מציין שהמקודד הגיאוגרפי לא החזיר התאמה מדויקת לבקשה המקורית, אבל הוא הצליח להתאים חלק מהכתובת המבוקשת. מומלץ לבדוק את הבקשה המקורית כדי לראות אם יש בה שגיאות כתיב או כתובת חלקית.התאמות חלקיות מתרחשות לרוב בכתובות רחוב שלא קיימות ביישוב שציינתם בבקשה. יכול להיות שיתקבלו גם התאמות חלקיות כשבקשה תואמת לשני מיקומים או יותר באותה יישוב. לדוגמה, 'Hillpar St, Bristol, UK' תחזיר התאמה חלקית גם לרחוב Henry וגם לרחוב Henrietta. שימו לב שאם בקשה כוללת רכיב של כתובת עם שגיאת איות, שירות הגיאוקוד עשוי להציע כתובת חלופית. הצעות שתופעלו באופן הזה יסומנו גם כהתאמה חלקית.
place_id
הוא מזהה ייחודי של מקום, שאפשר להשתמש בו עם ממשקי Google API אחרים. לדוגמה, אפשר להשתמש ב-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
: סכום המחיר הכולל, במטבע שצוין למעלה.
Directions Legs
הערה: שם האובייקט הקודם 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
היא הישות הבסיסית ביותר במסלול של הוראות הגעה, שמכילה שלב אחד שמתאר הוראה ספציפית אחת במסלול. לדוגמה: "Turn left at W. רחוב 4". השלב לא רק מתאר את ההוראה, אלא מכיל גם מידע על המרחק והמשך הזמן שקשורים לאופן שבו השלב הזה קשור לשלב הבא.
לדוגמה, שלב שמסומן בתור 'מעבר לכביש I-80 מערב' עשוי לכלול משך זמן של '37 מייל' ו'40 דקות', שמציין שהשלב הבא נמצא במרחק 37 מייל/40 דקות מהשלב הזה.
כשמשתמשים בשירות 'מסלולים' כדי לחפש מסלולים בתחבורה ציבורית, מערך השלבים יכלול מידע ספציפי על תחבורה ציבורית נוסף, בצורת אובייקט transit
. אם המסלול כולל כמה אמצעי תחבורה, יישלחו הוראות מפורטות לצעדים להליכה או לנהיגה במערך steps[]
.
לדוגמה, שלב הליכה יכלול הוראות מהמיקום ההתחלתי ועד למיקום הסיום: "הליכה אל Innes Ave & Fitch St". השלב הזה יכלול מסלול מפורט להולכי רגל במערך steps[]
, כמו: 'ממשיכים צפון-מערב', 'פונים שמאלה לרחוב Arelious 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
השם של התחנה או התחנה המרכזית של התחבורה הציבורית. למשל "Union Square".location
המיקום של התחנה או התחנה המרכזית של התחבורה הציבורית, שמיוצג כ-LatLng
.
- השדה
departure_stop
מכיל אובייקטTransitStop
שמייצג את התחנה/העצירה של היציאה. - השדה
arrival_time
מכיל את שעת ההגעה, שצוינה כאובייקטTime
עם שלושה מאפיינים:value
השעה שצוינה כאובייקטDate
של JavaScript.text
השעה שצוינה כמחרוזת. השעה מוצגת באזור הזמן של תחנת התחבורה הציבורית.- השדה
time_zone
מכיל את אזור הזמן של התחנה הזו. הערך הוא שם אזור הזמן כפי שהוא מוגדר במסד הנתונים של אזור הזמן IANA, למשל 'America/New_York'.
- השדה
departure_time
מכיל את שעת היציאה, שצוינה כאובייקטTime
. headsign
מציין את כיוון הנסיעה בקו הזה, כפי שהוא מסומן ברכב או בתחנת המוצא. בדרך כלל זו תהיה תחנת הקצה.headway
כשהאפשרות הזו זמינה, היא מציינת את מספר השניות הצפוי בין היציאות מאותה התחנה באותו זמן. לדוגמה, אם הערך שלheadway
הוא 600, צפויה המתנה של עשר דקות אם תחמיצו את האוטובוס.- השדה
line
מכיל אובייקט לינרי מסוגTransitLine
שמכיל מידע על קו התחבורה הציבורית שבו נעשה שימוש בשלב הזה. השדהTransitLine
מספק את השם והאופרטור של הקו, יחד עם מאפיינים אחרים שמפורטים במסמכי העזרה שלTransitLine
. - השדה
num_stops
מכיל את מספר העצירות בשלב הזה. כולל את תחנת העצירה של הנסיעה, אבל לא את תחנת העצירה של היציאה. לדוגמה, אם ההוראות כוללות יציאה מתחנה א', מעבר דרך תחנות ב' ו-ג' והגיע לתחנה ד', הפונקציהnum_stops
תחזיר את הערך 3.
קו תחבורה ציבורית
האובייקט TransitLine
חושף את המאפיינים הבאים:
- השדה
name
מכיל את השם המלא של קו התחבורה הציבורית. לדוגמה: '7 Avenue Express' או '14th St Crosstown'. - השדה
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
מכיל את סוג הרכב שבו נעשה שימוש בקו הזה. רשימה מלאה של הערכים הנתמכים מופיעה במאמר העזרה בנושא Vehicle 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
אפשר לבדוק את הרכיבים של DirectionsResults
– DirectionsRoute
, DirectionsLeg
, DirectionsStep
ו-TransitDetails
– ולהשתמש בהם בזמן ניתוח התשובה של המסלול.
חשוב: אם אתם מבצעים עיבוד של מסלולי תחבורה ציבורית באופן ידני במקום להשתמש באובייקט DirectionsRenderer
, עליכם להציג את השמות ואת כתובות ה-URL של חברות התחבורה הציבורית שמספקות את תוצאות הנסיעה.
בדוגמה הבאה מוצגת תצוגה גרפית של מסלול הליכה לאטרקציות תיירותיות מסוימות בניו יורק. אנחנו בודקים את DirectionsStep
של המסלול כדי להוסיף סמנים לכל שלב, ומצרפים מידע ל-InfoWindow
עם טקסט הדרכה לשלב הזה.
הערה: מכיוון שאנחנו מחשבים מסלולי הליכה, אנחנו גם מציגים למשתמש אזהרות בחלונית <div>
נפרדת.
var map; var directionsRenderer; var directionsService; var stepDisplay; var markerArray = []; function initMap() { // Instantiate a directions service. directionsService = new google.maps.DirectionsService(); // Create a map and center it on Manhattan. var manhattan = new google.maps.LatLng(40.7711329, -73.9741874); var mapOptions = { zoom: 13, center: manhattan } map = new google.maps.Map(document.getElementById('map'), mapOptions); // Create a renderer for directions and bind it to the map. var rendererOptions = { map: map } directionsRenderer = new google.maps.DirectionsRenderer(rendererOptions) // Instantiate an info window to hold step text. stepDisplay = new google.maps.InfoWindow(); } function calcRoute() { // First, clear out any existing markerArray // from previous calculations. for (i = 0; i < markerArray.length; i++) { markerArray[i].setMap(null); } // Retrieve the start and end locations and create // a DirectionsRequest using WALKING directions. var start = document.getElementById('start').value; var end = document.getElementById('end').value; var request = { origin: start, destination: end, travelMode: 'WALKING' }; // Route the directions and pass the response to a // function to create markers for each step. directionsService.route(request, function(response, status) { if (status == "OK") { var warnings = document.getElementById("warnings_panel"); warnings.innerHTML = "" + response.routes[0].warnings + ""; directionsRenderer.setDirections(response); showSteps(response); } }); } function showSteps(directionResult) { // For each step, place a marker, and add the text to the marker's // info window. Also attach the marker to an array so we // can keep track of it and remove it when calculating new // routes. var myRoute = directionResult.routes[0].legs[0]; for (var i = 0; i < myRoute.steps.length; i++) { var marker = new google.maps.Marker({ position: myRoute.steps[i].start_point, map: map }); attachInstructionText(marker, myRoute.steps[i].instructions); markerArray[i] = marker; } } function attachInstructionText(marker, text) { google.maps.event.addListener(marker, 'click', function() { stepDisplay.setContent(text); stepDisplay.open(map, marker); }); }
בגוף ה-HTML:
<div>
<strong>Start: </strong>
<select id="start">
<option value="penn station, new york, ny">Penn Station</option>
<option value="grand central station, new york, ny">Grand Central Station</option>
<option value="625 8th Avenue New York NY 10018">Port Authority Bus Terminal</option>
<option value="staten island ferry terminal, new york, ny">Staten Island Ferry Terminal</option>
<option value="101 E 125th Street, New York, NY">Harlem - 125th St Station</option>
</select>
<strong>End: </strong>
<select id="end" onchange="calcRoute();">
<option value="260 Broadway New York NY 10007">City Hall</option>
<option value="W 49th St & 5th Ave, New York, NY 10020">Rockefeller Center</option>
<option value="moma, New York, NY">MOMA</option>
<option value="350 5th Ave, New York, NY, 10118">Empire State Building</option>
<option value="253 West 125th Street, New York, NY">Apollo Theatre</option>
<option value="1 Wall St, New York, NY">Wall St</option>
</select>
<div>
שימוש בנקודות ציון במסלולים
כפי שצוין ב-DirectionsRequest, אפשר גם לציין נקודות עצירה (מסוג DirectionsWaypoint
) כשמחשבים מסלולים באמצעות שירות המסלולים לקבלת מסלולי הליכה, רכיבה על אופניים או נסיעה. אי אפשר להוסיף ציוני דרך למסלולים בתחבורה ציבורית.
נקודות ציון מאפשרות לחשב מסלולים דרך מיקומים נוספים, ובמקרה כזה המסלול המוחזר עובר דרך נקודות הציון הנתונות.
ה-waypoint
מורכב מהשדות הבאים:
location
(חובה) מציין את הכתובת של נקודת הציון.stopover
(אופציונלי) מציין אם נקודת הציון הזו היא עצירה בפועל במסלול (true
) או רק העדפה למסלול שחולף במיקום שצוין (false
). עצירות ביניים מוגדרות כברירת מחדל כ-true
.
כברירת מחדל, שירות המסלול מחשב מסלול דרך נקודות העצירה שצוינו בסדר שבו הן מוצגות. אפשר גם להעביר את הערך optimizeWaypoints: true
בתוך
DirectionsRequest
כדי לאפשר לשירות המסלול לבצע אופטימיזציה של המסלול שסופק על ידי סידור מחדש של נקודות העצירה בסדר יעיל יותר. (האופטימיזציה הזו היא יישום של
הבעיה של סוכן מכירות שפועל ברחבי העולם). זמן הנסיעה הוא הגורם העיקרי שאנחנו מבצעים אופטימיזציה שלו, אבל יכול להיות שנביא בחשבון גורמים אחרים כמו המרחק, מספר הפניות ועוד הרבה גורמים נוספים כשנבחר את המסלול היעיל ביותר. כדי ששירות המסלול יוכל לבצע אופטימיזציה של המסלול, כל נקודות העצירה חייבות להיות תחנות מעבר.
אם תבקשו משירות המסלול לבצע אופטימיזציה של הסדר של נקודות העצירה, הסדר שלהן יופיע בשדה waypoint_order
באובייקט DirectionsResult
.
בדוגמה הבאה מחושב מסלול חוצה-ארץ ברחבי ארצות הברית באמצעות מגוון של נקודות התחלה, נקודות סיום ונקודות ציון. (כדי לבחור כמה נקודות דרך, לוחצים על Ctrl-Click בזמן הבחירה של פריטים ברשימה).
שימו לב שאנחנו בודקים את השדות routes.start_address
ו-routes.end_address
כדי לספק לנו את הטקסט של נקודת ההתחלה ונקודת הסיום של כל מסלול.
TypeScript
function initMap(): void { const directionsService = new google.maps.DirectionsService(); const directionsRenderer = new google.maps.DirectionsRenderer(); const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 6, center: { lat: 41.85, lng: -87.65 }, } ); directionsRenderer.setMap(map); (document.getElementById("submit") as HTMLElement).addEventListener( "click", () => { calculateAndDisplayRoute(directionsService, directionsRenderer); } ); } function calculateAndDisplayRoute( directionsService: google.maps.DirectionsService, directionsRenderer: google.maps.DirectionsRenderer ) { const waypts: google.maps.DirectionsWaypoint[] = []; const checkboxArray = document.getElementById( "waypoints" ) as HTMLSelectElement; for (let i = 0; i < checkboxArray.length; i++) { if (checkboxArray.options[i].selected) { waypts.push({ location: (checkboxArray[i] as HTMLOptionElement).value, stopover: true, }); } } directionsService .route({ origin: (document.getElementById("start") as HTMLInputElement).value, destination: (document.getElementById("end") as HTMLInputElement).value, waypoints: waypts, optimizeWaypoints: true, travelMode: google.maps.TravelMode.DRIVING, }) .then((response) => { directionsRenderer.setDirections(response); const route = response.routes[0]; const summaryPanel = document.getElementById( "directions-panel" ) as HTMLElement; summaryPanel.innerHTML = ""; // For each route, display summary information. for (let i = 0; i < route.legs.length; i++) { const routeSegment = i + 1; summaryPanel.innerHTML += "<b>Route Segment: " + routeSegment + "</b><br>"; summaryPanel.innerHTML += route.legs[i].start_address + " to "; summaryPanel.innerHTML += route.legs[i].end_address + "<br>"; summaryPanel.innerHTML += route.legs[i].distance!.text + "<br><br>"; } }) .catch((e) => window.alert("Directions request failed due to " + status)); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
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;
מגבלות על נקודות דרך
חלות המגבלות והמגבלות הבאות על השימוש:
- המספר המקסימלי של נקודות דרך שמותר להשתמש בהן כשמשתמשים בשירות 'מסלולים' בממשק API של JavaScript במפות Google הוא 25, בנוסף לנקודת המוצא וליעד. המגבלות זהות גם לשירות האינטרנט של Directions API.
- ב שירות האינטרנט של Directions API, הלקוחות יכולים להשתמש ב-25 נקודות ציון, בנוסף לנקודת המוצא וליעד.
- לקוחות עם תוכנית פרימיום של פלטפורמת מפות Google יכולים להשתמש ב-25 נקודות ציון, בנוסף לנקודת המוצא וליעד.
- אין תמיכה בציוני דרך במסלולי תחבורה ציבורית.
מסלול שניתן לגרירה
משתמשים יכולים לשנות מסלולים לרכיבה על אופניים, להליכה או לנהיגה שמוצגים באמצעות DirectionsRenderer
באופן דינמי, אם הם ניתנים לגרירה. כך, משתמשים יכולים לבחור מסלולים ולשנות אותם בלחיצה על הנתיבים שנוצרו במפה וגרירה שלהם.
כדי לציין אם התצוגה של המרינר מאפשרת לגרור מסלול, מגדירים את המאפיין draggable
לערך true
. אי אפשר לגרור מסלולים בתחבורה ציבורית.
כשאפשר לגרור מסלולים, המשתמש יכול לבחור כל נקודה בנתיב (או בנקודת ציון) של התוצאה שעבר רינדור ולהעביר את הרכיב שצוין למיקום חדש. הערך של DirectionsRenderer
יתעדכן באופן דינמי כדי להציג את הנתיב ששונה. אחרי ההשקה, יתווסף למפה ציון דרך ביניים (שיסומן בסמן לבן קטן). בחירה והזזה של מקטע נתיב ישנו את הקטע הזה במסלול, ואילו בחירה והזזה של סמן נקודת ציון (כולל נקודות ההתחלה והסיום) ישנו את הקטעים במסלול שעוברים דרך נקודת הציון הזו.
מכיוון שהמסלול שניתן לגרירה משתנה ועובר עיבוד בצד הלקוח, מומלץ לעקוב אחרי האירוע directions_changed
ב-DirectionsRenderer
ולטפל בו כדי לקבל התראה כשהמשתמש משנה את המסלול המוצג.
הקוד הבא מציג נסיעה מפרת' בחוף המערבי של אוסטרליה לסידני בחוף המזרחי. הקוד עוקב אחרי האירוע directions_changed
כדי לעדכן את המרחק הכולל של כל השלבים במסלול.
TypeScript
function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 4, center: { lat: -24.345, lng: 134.46 }, // Australia. } ); const directionsService = new google.maps.DirectionsService(); const directionsRenderer = new google.maps.DirectionsRenderer({ draggable: true, map, panel: document.getElementById("panel") as HTMLElement, }); directionsRenderer.addListener("directions_changed", () => { const directions = directionsRenderer.getDirections(); if (directions) { computeTotalDistance(directions); } }); displayRoute( "Perth, WA", "Sydney, NSW", directionsService, directionsRenderer ); } function displayRoute( origin: string, destination: string, service: google.maps.DirectionsService, display: google.maps.DirectionsRenderer ) { service .route({ origin: origin, destination: destination, waypoints: [ { location: "Adelaide, SA" }, { location: "Broken Hill, NSW" }, ], travelMode: google.maps.TravelMode.DRIVING, avoidTolls: true, }) .then((result: google.maps.DirectionsResult) => { display.setDirections(result); }) .catch((e) => { alert("Could not display directions due to: " + e); }); } function computeTotalDistance(result: google.maps.DirectionsResult) { let total = 0; const myroute = result.routes[0]; if (!myroute) { return; } for (let i = 0; i < myroute.legs.length; i++) { total += myroute.legs[i]!.distance!.value; } total = total / 1000; (document.getElementById("total") as HTMLElement).innerHTML = total + " km"; } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
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;