סקירה
השירות 'מטריצת מרחק' של Google מחשב את המרחק ואת משך הנסיעה בין מקורות ויעדים שונים באמצעות אמצעי נסיעה נתון.
שירות זה לא מחזיר מידע מפורט על המסלול. כדי לקבל מידע על מסלול, כולל קווים פוליגוניים והנחיות טקסט, צריך להעביר את נקודת המוצא והיעד הרצויים לשירות המסלול.
איך מתחילים
לפני שמשתמשים בשירות Distance Matrix ב-Maps JavaScript API, צריך לוודא ש-Advanced Matrix API מופעל במסוף Google Cloud באותו פרויקט שהגדרת ל-Maps JavaScript API.
כדי להציג את רשימת ממשקי ה-API המופעלים:
- נכנסים אל מסוף Google Cloud.
- לוחצים על הלחצן Select a project, בוחרים את אותו הפרויקט שהגדרתם ב-Maps JavaScript API ולוחצים על Open.
- ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Destination Matrix API.
- אם ה-API מופיע ברשימה, אז לא צריך לבצע פעולה נוספת. אם ה-API לא מופיע ברשימה,
מפעילים אותו:
- בחלק העליון של הדף לוחצים על ENABLE API כדי להציג את הכרטיסייה ספרייה. לחלופין, בתפריט שמשמאל לוחצים על Library.
- מחפשים את Distance Matrix API ובוחרים אותו מרשימת התוצאות.
- בוחרים באפשרות הפעלה. כשהתהליך יסתיים, האפשרות Distance Matrix API יופיע ברשימת ממשקי ה-API במרכז הבקרה.
תמחור ומדיניות
תמחור
החל מ-16 ביולי 2018 נכנסה לתוקף תוכנית תמחור ותשלומים חדשה לפי שימוש במפות, במסלולים ובמקומות. למידע נוסף על התמחור החדש ומגבלות השימוש לשימוש בשירות JavaScript Destination Matrix, ראו שימוש וחיוב ל-Distance Matrix API.
הערה: כל שאילתה שנשלחת לשירות 'מטריצת מרחק' מוגבלת במספר הרכיבים המותרים. מספר המקורות כפול מספר היעדים שמגדירים את מספר הרכיבים.
כללי מדיניות
השימוש בשירות Destination Matrix חייב להיות בהתאם למדיניות שמתוארת של Distance Matrix API.
בקשות של מטריצת מרחק
הגישה לשירות 'מטריצת מרחק' היא אסינכרונית, כי ה-API של מפות Google צריך לשלוח קריאה לשרת חיצוני. לכן צריך להעביר שיטת קריאה חוזרת (callback) שתבוצע בסיום הבקשה כדי לעבד את התוצאות.
ניגשים לשירות Distance Matrix בתוך הקוד דרך האובייקט google.maps.DistanceMatrixService
constructor.
ה-method DistanceMatrixService.getDistanceMatrix()
מפעילה בקשה לשירות 'מטריצת מרחק' ומעבירה לו ליטרל של אובייקט DistanceMatrixRequest
שמכיל את המקורות, היעדים ומצב הנסיעה, וגם שיטת קריאה חוזרת שתבוצע לאחר קבלת התשובה.
var origin1 = new google.maps.LatLng(55.930385, -3.118425); var origin2 = 'Greenwich, England'; var destinationA = 'Stockholm, Sweden'; var destinationB = new google.maps.LatLng(50.087692, 14.421150); var service = new google.maps.DistanceMatrixService(); service.getDistanceMatrix( { origins: [origin1, origin2], destinations: [destinationA, destinationB], travelMode: 'DRIVING', transitOptions: TransitOptions, drivingOptions: DrivingOptions, unitSystem: UnitSystem, avoidHighways: Boolean, avoidTolls: Boolean, }, callback); function callback(response, status) { // See Parsing the Results for // the basics of a callback function. }
השדה DistanceMatrixRequest
מכיל את השדות הבאים:
origins
(חובה) – מערך שמכיל מחרוזת כתובת אחת או יותר, אובייקטgoogle.maps.LatLng
או אובייקט Place שממנו צריך לחשב מרחק וזמן.destinations
(חובה) – מערך שמכיל מחרוזת כתובת אחת או יותר, אובייקטgoogle.maps.LatLng
או אובייקט Place שאליו צריך לחשב מרחק וזמן.travelMode
(אופציונלי) – אמצעי התחבורה שבו משתמשים לחישוב מסלול. אפשר לעיין בקטע אמצעי נסיעה.transitOptions
(אופציונלי) – האפשרויות שחלות רק על בקשות שבהןtravelMode
הואTRANSIT
. הערכים החוקיים מתוארים בקטע אפשרויות תחבורה ציבורית.drivingOptions
(אופציונלי) מציין ערכים שרלוונטיים רק לבקשות שבהןtravelMode
הואDRIVING
. הערכים החוקיים מתוארים בקטע אפשרויות נהיגה.unitSystem
(אופציונלי) — מערכת היחידה שבה צריך להשתמש להצגת המרחק. הערכים הקבילים הם:-
google.maps.UnitSystem.METRIC
(ברירת מחדל) google.maps.UnitSystem.IMPERIAL
-
avoidHighways
(אופציונלי) – אם הערך שלtrue
, המסלולים בין נקודות המוצא והיעדים יחושבו כדי להימנע מכבישים מהירים ככל האפשר.avoidTolls
(אופציונלי) – אםtrue
, המסלול בין הנקודות יחושב באמצעות מסלולים שאינם כבישי אגרה, ככל האפשר.
מצבי נסיעה
כשמחשבים זמנים ומרחקים, אפשר לציין באיזה אמצעי תחבורה להשתמש. כרגע יש תמיכה באמצעי הנסיעה הבאים:
BICYCLING
מבקש מסלול לאופניים דרך שבילי אופניים ורחובות מועדפים (זמין כרגע רק בארה "ב ובחלק מהערים בקנדה).DRIVING
(ברירת מחדל) מציין מסלול נסיעה רגיל באמצעות רשת הכבישים.- התקבלה בקשה של
TRANSIT
למסלול דרך מסלולים של תחבורה ציבורית. אפשר לציין את האפשרות הזו רק אם הבקשה כוללת מפתח API. בקטע על אפשרויות תחבורה ציבורית מפורטות האפשרויות הזמינות בסוג הבקשה הזה. WALKING
מבקש/ת מסלול הליכה דרך שבילים להולכי רגל ומדרכות (היכן שזמין).
אפשרויות תחבורה ציבורית
בשלב זה, שירות התחבורה הציבורית הוא 'ניסיוני'. במהלך השלב הזה ניישם הגבלות קצב של יצירת ��קשות כדי למנוע ניצול לרעה של API. בסופו של דבר נאכוף הגבלה על סך כל השאילתות לכל טעינת מפה, על סמך שימוש הוגן ב-API.
האפשרויות הזמינות לבקשה של מטריצת מרחק משתנות בהתאם למצבי הנסיעה.
בבקשות להעברה, המערכת מתעלמת מהאפשרויות avoidHighways
ו-avoidTolls
. אפשר לציין אפשרויות ניתוב ספציפיות לתחבורה ציבורית באמצעות הליטרל של האובייקט TransitOptions
.
בקשות לתחבורה ציבורית הן דחופות. החישובים יוחזרו רק לזמנים עתידיים.
הליטרל של האובייקט TransitOptions
מכיל את השדות הבאים:
{ arrivalTime: Date, departureTime: Date, modes: [transitMode1, transitMode2] 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
מציין שהמסלול המחושב צריך להעדיף מספר מוגבל של הליכה.
אפשרויות נהיגה
אפשר להשתמש באובייקט drivingOptions
כדי לציין זמן יציאה
לצורך חישוב המסלול הטוב ביותר אל היעד בהתאם לתנאי התנועה הצפויים. אפשר גם לציין אם רוצים שזמן התנועה המשוער יהיה פסימי או אופטימי, או
ההערכה הטובה ביותר על סמך תנאי תנועה היסטוריים ותנועה בזמן אמת.
האובייקט drivingOptions
מכיל את השדות הבאים:
{ departureTime: Date, trafficModel: TrafficModel }
הסבר על השדות האלה:
departureTime
(כדי שהליטרל של האובייקטdrivingOptions
יהיה חוקי) מציין את זמן היציאה הרצוי כאובייקטDate
. צריך להגדיר את הערך ל��עה הנוכחית או לזמן כלשהו בעתיד. תאריך ההתחלה לא יכול להיות בעבר. (ה-API ממ��ר את ��ל התאריכים ל-UTC כדי להבטיח טיפול עקבי באזורי הזמן השונים). אם כוללים את המאפייןdepartureTime
בבקשה, ה-API מחזיר את המסלול הטוב ביותר בהתאם לתנאי התנועה הצפויים באותו זמן, וכולל את הזמן החזוי לתנועה (duration_in_traffic
) בתגובה. אם לא מציינים זמן יציאה (כלומר, אם הבקשה לא כוללת אתdrivingOptions
), המסלול שמוחזר הוא מסלול טוב בדרך כלל, בלי להביא בחשבון את מצב התנועה.trafficModel
(אופציונלי) מציין את ההנחות שצריך להשתמש בהן לחישוב הזמן בתנועה. ההגדרה הזו משפיעה על הערך שמוחזר בשדהduration_in_traffic
בתגובה, שמכיל את משך הזמן החזוי בתנועה על סמך ממוצעים היסטוריים. ברירת המחדל היאbest_guess
. מותר להזין את הערכים הבאים:bestguess
(ברירת המחדל) מציין שהשדהduration_in_traffic
שמוחזר צריך להיות האומדן הטוב ביותר של זמן הנסיעה, בהינתן המידע שידוע גם לגבי מצב התנועה בעבר וגם בזמן אמת. התנועה בזמן אמת הופכת לחשובה יותר ככל שמתקרבים יותר אלdepartureTime
.pessimistic
מציין שהשדהduration_in_traffic
שמוחזר צריך להיות ארוך יותר מזמן הנסיעה בפועל ברוב הימים, אבל בימים החריגים שבהם יש עומסי תנועה מסוימים עשויים לחרוג מהערך הזה.optimistic
מציין שהשדהduration_in_traffic
שמוחזר צריך להיות קצר יותר מזמן הנסיעה בפועל ברוב הימים, אם כי ימים מזדמנים עם תנאי תנועה טובים במיוחד עשויים להיות מהירים יותר מהערך הזה.
בהמשך מוצגת דוגמה DistanceMatrixRequest
למסלולי נהיגה,
כולל שעת יציאה ומודל תנועה:
{ origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'], destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}], travelMode: 'DRIVING', drivingOptions: { departureTime: new Date(Date.now() + N), // for the time N milliseconds from now. trafficModel: 'optimistic' } }
תגובות של מטריצת מרחק
קריאה מוצלחת לשירות Distance Matrix מחזירה אובייקט DistanceMatrixResponse
ואובייקט DistanceMatrixStatus
. הן מועברות לפונקציית הקריאה החוזרת
שציינתם בבקשה.
האובייקט DistanceMatrixResponse
מכיל מידע על המרחק
ומשך הזמן של כל צמד של מקור/יעד שעבורו אפשר לחשב מסלול.
{ "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ], "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ], "rows": [ { "elements": [ { "status": "OK", "duration": { "value": 70778, "text": "19 hours 40 mins" }, "distance": { "value": 1887508, "text": "1173 mi" } }, { "status": "OK", "duration": { "value": 44476, "text": "12 hours 21 mins" }, "distance": { "value": 1262780, "text": "785 mi" } } ] }, { "elements": [ { "status": "OK", "duration": { "value": 96000, "text": "1 day 3 hours" }, "distance": { "value": 2566737, "text": "1595 mi" } }, { "status": "OK", "duration": { "value": 69698, "text": "19 hours 22 mins" }, "distance": { "value": 1942009, "text": "1207 mi" } } ] } ] }
תוצאות של מטריצת המרחק
בהמשך מוסבר על השדות הנתמכים בתשובה.
originAddresses
הוא מערך שמכיל את המיקומים שמועברים בשדהorigins
בבקשה של מטריצת המרחק. הכתובות מוחזרות כפי שהן מעוצבות על ידי הקואורדינטות.destinationAddresses
הוא מערך שמכיל את המיקומים שהועברו בשדהdestinations
, בפורמט שמוחזר על ידי הקואורדינטות.rows
הוא מערך שלDistanceMatrixResponseRow
אובייקטים, כאשר כל שורה תואמת למקור.elements
הם צאצאים שלrows
, והם תואמים בין מקור השורה לבין כל יעד. הם כוללים מידע על הסטטוס, משך הנסיעה, המרחק ומחיר הכרטיס (אם יש) לגבי כל צמד של נקודות מוצא או יעד.- כל
element
מכיל את השדות הבאים:status
: קודי סטטוס עם רשימה של קודי סטטוס אפשרייםduration
: משך הזמן שנדרש כדי לנסוע במסלול הזה, מבוטא בשניות (השדהvalue
) וכ-text
. הערך הטקסטואלי מעוצב בהתאם ל-unitSystem
שצוין בבקשה (או במדד, אם לא צוינה העדפה).duration_in_traffic
: משך הזמן שנדרש כדי לנסוע במסלול הזה תוך התייחסות למצב התנועה הנוכחי, בשניות (השדהvalue
) ובתורtext
. הערך הטקסטואלי מעוצב בהתאם ל-unitSystem
שצוין בבקשה (או במדד, אם לא צוינה העדפה). השדהduration_in_traffic
מוחזר רק כאשר יש נתוני תנועה,mode
מוגדר ל-driving
ו-departureTime
נכלל כחלק מהשדהdistanceMatrixOptions
בבקשה.distance
: המרחק הכולל של המסלול הזה, מבוטא במטרים (value
) וכ-text
. הערך הטקסטואלי מעוצב בהתאם ל-unitSystem
שצוין בבקשה (או במדד, אם לא סופקה העדפה).fare
: מכיל את מחיר הכרטיס הכולל (כלומר, את עלויות הכרטיסים הכוללות) במסלול הזה. הנכס הזה מוחזר רק לבקשות של תחבורה ציבורית ורק לספקי תחבורה ציבורית שבהם יש מידע על מחיר הכרטיס. המידע כולל:currency
: קוד מטבע לפי תקן ISO 4217 שמציין את המטבע שבו מצוין הסכום.value
: סכום המחיר הכולל, במטבע שצוין למעלה.
קודי סטטוס
התשובה 'מטריצת המרחק' כוללת קוד סטטוס של התגובה כולה וסטטוס של כל רכיב.
קודי סטטוס תגובה
קודי סטטוס שחלים על DistanceMatrixResponse
מועברים באובייקט DistanceMatrixStatus
וכוללים:
OK
– הבקשה תקפה. הסטטוס הזה יכול להחזיר גם אם לא נמצאו מסלולים בין נקודות המוצא והיעדים. למידע על הסטטוס ברמת הרכיב, ראו קודי סטטוס של הרכיבים.INVALID_REQUEST
– הבקשה שצוינה לא הייתה חוקית. בדרך כלל הסיבה לכך היא שחסרים שדות חובה. ברשימת השדות הנתמכים מפורטת למעלה.MAX_ELEMENTS_EXCEEDED
– המכפלה של המקורות והיעדים חורגת מהמגבלה לכל שאילתה.MAX_DIMENSIONS_EXCEEDED
– הבקשה שלך הכילה יותר מ-25 מקורות, או יותר מ-25 יעדים.OVER_QUERY_LIMIT
– האפליקציה ביקשה יותר מדי רכיבים בפרק הזמן המותר. הבקשה אמורה להצליח אם יתבצע ניסיון חוזר אחרי פרק זמן סביר.REQUEST_DENIED
– השירות דחה את השימוש בשירות 'מטריצת מרחק' בדף האינטרנט שלך.UNKNOWN_ERROR
– לא ניתן היה לעבד בקשה של מטריצת מרחק בגלל שגיאה בחיבור לשרת. אם תנסו שוב, יכול להיות שהבקשה תאושר.
קודי סטטוס של רכיבים
קודי הסטטוס הבאים חלים על אובייקטים ספציפיים של DistanceMatrixElement
:
NOT_FOUND
— לא ניתן היה לקודד את הקוד הגיאוגרפי של המקור ו/או היעד של ההתאמה.OK
– התשובה תכיל תוצאה תקינה.ZERO_RESULTS
– לא נמצא מסלול בין נקודת היציאה ליעד.
ניתוח התוצאות
האובייקט DistanceMatrixResponse
מכיל row
אחד לכל מקור שהועבר בבקשה. כל שורה מכילה שדה element
לכל התאמה של המקור הזה עם היעדים שצוינו.
function callback(response, status) { if (status == 'OK') { var origins = response.originAddresses; var destinations = response.destinationAddresses; for (var i = 0; i < origins.length; i++) { var results = response.rows[i].elements; for (var j = 0; j < results.length; j++) { var element = results[j]; var distance = element.distance.text; var duration = element.duration.text; var from = origins[i]; var to = destinations[j]; } } } }