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

סקירה כללית

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

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

תחילת העבודה

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

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

1. נכנסים ל מסוף Google Cloud.
2. לוחצים על הלחצן Select a project, בוחרים את אותו פרויקט שהגדרתם עבור Maps JavaScript API ולוחצים על Open.
3. ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Distance Matrix API (Legacy).
4. אם ה-API מופיע ברשימה, הכול מוכן. אם ה-API לא מופיע ברשימה, מפעילים אותו בכתובת https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com

תמחור ומדיניות

תמחור

מידע על התמחור ומדיניות השימוש בשירות מטריצת המרחקים של JavaScript זמין במאמר בנושא שימוש וחיוב של Distance Matrix API (גרסה קודמת).

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

מדיניות

השימוש בשירות Distance Matrix חייב להיות בהתאם למדיניות שמתוארת עבור Distance Matrix API (גרסה קודמת).

בקשות Distance Matrix

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

אתם ניגשים לשירות Distance Matrix בקוד באמצעות אובייקט הבנאי google.maps.DistanceMatrixService. השיטה DistanceMatrixService.getDistanceMatrix() יוזמת בקשה לשירות Distance Matrix, ומעבירה אליה אובייקט מילולי 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

קריאה מוצלחת לשירות 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: סכום התעריף הכולל, במטבע שצוין למעלה.

קודי סטטוס

התשובה של Distance Matrix כוללת קוד סטטוס לתשובה כולה, וגם סטטוס לכל רכיב.

קודי סטטוס של תגובות

קודי הסטטוס שרלוונטיים ל-DistanceMatrixResponse מועברים באובייקט DistanceMatrixStatus וכוללים:

• ‫OK — הבקשה תקפה. המערכת יכולה להחזיר את הסטטוס הזה גם אם לא נמצאו מסלולים בין אף אחד מנקודות המוצא ליעדים. מידע על סטטוס ברמת הרכיב מופיע במאמר קודי סטטוס של רכיב.
• ‫INVALID_REQUEST — הבקשה שסופקה לא תקינה. הסיבה לכך היא בדרך כלל שחסרים שדות חובה. כאן מופיעה רשימת השדות הנתמכים.
• ‫MAX_ELEMENTS_EXCEEDED — מכפלת המקורות והיעדים חורגת מהמגבלה לכל שאילתה.
• ‫MAX_DIMENSIONS_EXCEEDED — הבקשה שלך הכילה יותר מ-25 מקורות או יותר מ-25 יעדים.
• ‫OVER_QUERY_LIMIT – האפליקציה שלך ביקשה יותר מדי אלמנטים בפרק הזמן המותר. הבקשה אמורה להצליח אם תנסו שוב אחרי פרק זמן סביר.
• ‫REQUEST_DENIED — השירות דחה את השימוש בשירות Distance Matrix בדף האינטרנט שלכם.
• ‫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];
      }
    }
  }
}