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