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

סקירה כללית

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

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

תחילת העבודה

לפני השימוש בשירות 'מטריצת מרחק' ב-Maps JavaScript API, קודם צריך לוודא ש-Destination 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 כדי להציג את ספרייה. לחלופין, בתפריט שבצד שמאל, בוחרים באפשרות ספרייה.
    2. מחפשים את Distance Matrix API ובוחרים אותו מרשימת התוצאות.
    3. בוחרים באפשרות הפעלה. כשהתהליך מסתיים, Destination Matrix API מופיעה ברשימת ממשקי ה-API מרכז השליטה.

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

תמחור

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

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

מדיניות

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

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

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

ניגשים לשירות 'מטריצת מרחק' מתוך הקוד דרך האובייקט google.maps.DistanceMatrixService של ה-constructor. השיטה 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 אובייקטים או מקום אובייקטים שצריך לחשב אליהם את המרחק ואת הזמן.
  • travelMode (אופציונלי) – המצב של שבה נעשה שימוש בעת חישוב מסלול. צפייה בקטע שעוסק ב- אמצעי הגעה.
  • transitOptions (אופציונלי) – אפשרויות חלות רק על בקשות שבהן travelMode TRANSIT מתוארים ערכים חוקיים בקטע על אפשרויות תחבורה ציבורית.
  • drivingOptions (אופציונלי) מציין ערכים החלים רק על בקשות שבהן travelMode DRIVING מתוארים ערכים חוקיים בקטע אפשרויות נהיגה.
  • unitSystem (אופציונלי) — מערכת היחידה כדי להשתמש בו להצגת המרחק. הערכים הקבילים הם:
    • ‫google.maps.UnitSystem.METRIC (ברירת מחדל)
    • google.maps.UnitSystem.IMPERIAL
  • avoidHighways (אופציונלי) – אם true, המסלולים בין נקודות המוצא והיעדים יהיו מחושב כדי להימנע מכבישים מהירים במידת האפשר.
  • avoidTolls (אופציונלי) – אם true, המסלול בין הנקודות יחושב באמצעות מסלולים ללא כבישי אגרה, ככל האפשר.

מצבי נסיעה

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

  • BICYCLING בקשות מסלולי אופניים דרך מסלולי אופניים רחובות מועדפים (זמינותה כרגע רק בארה"ב ובחלק מהערים בקנדה).
  • DRIVING (ברירת המחדל) מציין מסלול נסיעה רגיל באמצעות רשת הדרכים.
  • TRANSIT מבקש מסלול דרך מסלולים של תחבורה ציבורית. אפשר לציין את האפשרות הזו רק אם הבקשה שכולל מפתח API. לפרטים על תחבורה ציבורית options לאפשרויות הזמינות בסוג הבקשה הזה.
  • 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 מוחזר רק כאשר יש נתוני תנועה, mode מוגדר כ-driving, וגם departureTime נכלל כחלק מ השדה distanceMatrixOptions בבקשה.
    • distance: המרחק הכולל של המסלול הזה, מבוטא ב מטרים (value) ו-text. הערך הטקסטואלי בפורמט שתואם לunitSystem שצוין request (או במדד, אם לא סופקה העדפה).
    • 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];
      }
    }
  }
}