סקירה כללית
שירות מטריצת המרחקים של Google מחשב את המרחק ומשך הנסיעה בין מספר מקורות ויעדים באמצעות אמצעי התחבורה.
השירות הזה לא מחזיר מידע מפורט על המסלול. אפשר לקבל מידע על המסלול, כולל מצולמים והוראות טקסט, דרך נקודת המוצא והיעד הרצויים לשירות המסלול.
איך מתחילים
לפני השימוש בשירות 'מטריצת מרחק' בממשק ה-API של מפות Google JavaScript, יש לוודא שה-API של מטריצת המרחק מופעל ב-Google Cloud Console, באותו פרויקט שהגדרת ל-Maps JavaScript API.
כדי להציג את רשימת ממשקי ה-API המופעלים:
- נכנסים ל- Google Cloud Console.
- לוחצים על הלחצן Select a project, בוחרים את הפרויקט שהגדרתם ב-Maps JavaScript API ולוחצים על Open.
- ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את DISTANCE Matrix API.
- אם ה-API מופיע ברשימה, הכול מוכן. אם ה-API לא מופיע,
מפעילים אותו:
- בחלק העליון של הדף, בוחרים באפשרות הפעלת API כדי להציג את הכרטיסייה ספרייה. לחלופין, בתפריט שמימין בוחרים באפשרות ספרייה.
- מחפשים את המרחק מטריצת API ובוחרים אותו מרשימת התוצאות.
- לוחצים על הפעלה. בסיום התהליך, המרחק מטריצת מופיע ברשימת ממשקי ה-API ב מרכז הבקרה.
תמחור ומדיניות
תמחור
ב-16 ביולי 2018 תיכנס לתוקף תוכנית תמחור חדשה מסוג 'תשלום לפי שימוש' עבור מפות Google, מסלולים ומקומות. מידע נוסף על המגבלות החדשות ועל השימוש במגבלות השימוש בשירות מטריצת המרחקים של JavaScript מפורט במאמר שימוש וחיוב ב-API של מטריצת המרחקים.
הערה: כל שאילתה שנשלחת לשירות מטריצת המרחק מוגבלת על ידי מספר הרכיבים המותרים, כאשר מספר המקורות כפול מספר היעדים מגדיר את מספר הרכיבים.
מדיניות
השימוש בשירות 'מטריצת מרחק' חייב להיות בהתאם למדיניות שמפורטת עבור ה-API של מטריצת המרחקים.
בקשות מטריצת מרחקים
הגישה לשירות מטריצת המרחקים היא אסינכרונית, מאחר שה-API של מפות Google צריך לבצע קריאה לשרת חיצוני. לכן צריך לעבור לשיטת callback כדי לבצע את הבקשה כשהיא מסתיימת.
ניתן לגשת לשירות מטריצת המרחק שבתוך הקוד דרך אובייקט הבנייה google.maps.DistanceMatrixService
.
השיטה DistanceMatrixService.getDistanceMatrix()
מפעילה בקשה לשירות מטריצת המרחקים ומעבירה אותה ליטרל של אובייקט DistanceMatrixRequest
שמכיל את המקורות, היעדים ומצב הנסיעה, וגם שיטה לקריאה חוזרת (callback) עם קבלת התגובה.
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
או אובייקט המשמשים לחישוב המרחק והזמן.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
מבקש מסלולי אופניים באמצעות שבילי אופניים ורחובות מועדפים (כרגע זמין רק בארה & quot;ב ובערים מסוימות בקנדה).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' } }
תגובות מטריצת מרחקים
קריאה מוצלחת לשירות 'מטריצת מרחק' מחזירה אובייקט
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
מוחזר רק ללקוחות בתוכנית הפרימיום של מפות Google, שבהם נתוני התנועה זמינים, הערך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]; } } } }