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

סקירה כללית

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

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

תחילת העבודה

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

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

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

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

תמחור

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

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

כללי מדיניות

השימוש בשירות 'מטריצת מרחק' חייב להיות בהתאם למדיניות שמתוארת של Formula Matrix API.

בקשות למטריצת מרחק

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

ניתן לגשת לשירות 'מטריצת מרחק' בתוך הקוד דרך אובייקט ה-constructor של google.maps.DistanceMatrixService. השיטה 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'
  }
}

תגובות של מטריצת מרחק

קריאה מוצלחת לשירות מטריצת מרחקים מחזירה אובייקט DistanceMatrixResponse ואובייקט DistanceMatrixStatus. הם מועברות לפונקציית הקריאה החוזרת (callback) שציינת בבקשה.

האובייקט 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];
      }
    }
  }
}