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

סקירה כללית

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

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

תחילת העבודה

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

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

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

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

תמחור

החל מ-16 ביולי 2018, תוכנית תמחור חדשה של תשלום לפי שימוש נכנסה לתוקף במפות Google, במסלולים ובמקומות. למידע נוסף על התמחור והמגבלות החדשות לשימוש בשירות מטריצת המרחקים ב-JavaScript, קראו את המאמר שימוש וחיוב בנושא Distance Matrix API.

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

מדיניות

השימוש בשירות Distance Matrix חייב להיות בהתאם למדיניות שמתוארת ב-Distance Matrix API.

בקשות של Distance Matrix

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

כדי לגשת לשירות Distance Matrix בקוד, משתמשים באובייקט ה-constructor‏ google.maps.DistanceMatrixService. ה-method‏ DistanceMatrixService.getDistanceMatrix() יוצר בקשה לשירות Distance Matrix, מעביר לו אובייקט DistanceMatrixRequest ליטרלי שמכיל את נקודות המוצא, את נקודות היעד ואת אופן הנסיעה, וגם method של קריאה חוזרת (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 או אובייקטים מסוג 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];
      }
    }
  }
}