שירות מטריצת מרחקים

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

בדף הזה מתואר השירות בצד הלקוח שזמין באמצעות Maps JavaScript API. אם אתם רוצים לעבוד עם שירותי האינטרנט של מפות Google בשרת שלכם, שימו לב ללקוח Node.js לשירותי מפות Google. בדף שבקישור הזה מוצגים גם לקוח Java, לקוח Python ולקוח Go לשירותי מפות Google.

סקירה

כדאי לעיין גם בחומר העזר בנושא JavaScript של API של מפות Google: מטריצת מרחק

השירות 'מטריצת מרחק' של Google מחשב את המרחק ואת משך הנסיעה בין מקורות ויעדים שונים באמצעות אמצעי נסיעה נתון.

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

איך מתחילים

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

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

1. נכנסים אל מסוף Google Cloud.
2. לוחצים על הלחצן Select a project, בוחרים את אותו הפרויקט שהגדרתם ב-Maps JavaScript API ולוחצים על Open.
3. ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Destination Matrix API.
4. אם ה-API מופיע ברשימה, אז לא צריך לבצע פעולה נוספת. אם ה-API לא מופיע ברשימה, מפעילים אותו:
   1. בחלק העליון של הדף לוחצים על ENABLE API כדי להציג את הכרטיסייה ספרייה. לחלופין, בתפריט שמשמאל לוחצים על Library.
   2. מחפשים את Distance Matrix API ובוחרים אותו מרשימת התוצאות.
   3. בוחרים באפשרות הפעלה. כשהתהליך יסתיים, האפשרות 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, המסלול בין הנקודות יחושב באמצעות מסלולים שאינם כבישי אגרה, ככל האפשר.

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

מצבי נסיעה

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

• 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];
      }
    }
  }
}