קבלת מטריצת מסלול

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

מגבלות של בקשות

השיטה RouteMatrix.computeRouteMatrix() אוכפת את מגבלות הבקשה הבאות לנקודות ציון באמצעות כתובת או מופעים של מקומות, ולפריטים. הפריטים הם המסלולים בין כל נקודת מוצא לכל יעד במטריצת מסלולים, ולכן מספר הפריטים הוא מספר נקודות המוצא כפול מספר היעדים. לדוגמה, אם יש לכם 10 נקודות מוצא ו-10 יעדים, יהיו לכם 100 פריטים:

  • מספר הפריטים לא יכול להיות גדול מ-625 במסלולים שהם לא מסלולי TRANSIT.
  • אם מציינים TRANSIT נתיב, מספר הפריטים לא יכול להיות יותר מ-100.
  • אם מציינים את TRAFFIC_AWARE_OPTIMAL, מספר הפריטים לא יכול להיות גדול מ-100.
  • אם מציינים מקורות או יעדים באמצעות כתובות או מופעים של Place, אפשר לציין עד 50 כתובות או מופעים בסך הכול.

דוגמה לבקשה של מטריצת מסלולים

בדוגמה הבאה מוצג ComputeRouteMatrixRequest. בדוגמה הזו: הפעולות הבאות מתבצעות:

  • הדוגמה הבאה מראה איך מציינים מערך של שתי נקודות מוצא ושתי נקודות יעד. השיטה מחשבת מסלול מכל נקודת מוצא לכל יעד, ולכן התשובה מכילה ארבעה מסלולים.
    במערך, האינדקס של הרכיב הראשון הוא 0, האינדקס של הרכיב השני הוא 1 וכן הלאה.
  • מציינים את השדות שרוצים להחזיר. בדוגמה הזו, מגדירים את הבקשה כך שתחזיר את הערכים durationMillis, distanceMeters ו-condition לכל מסלול. 
const request = {
  origins: [origin1, origin2],
  destinations: [destinationA, destinationB],
  travelMode: google.maps.TravelMode.DRIVING,
  units: google.maps.UnitSystem.METRIC,
  fields: ['durationMillis', 'distanceMeters', 'condition'], 
};

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

"matrix": {
  "rows": [
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 202587,
          "durationMillis": 10040000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 252734,
          "durationMillis": 12240000
        }
      ]
    },
    {
      "items": [
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 166135,
          "durationMillis": 6596000
        },
        {
          "condition": "ROUTE_EXISTS",
          "distanceMeters": 216282,
          "durationMillis": 8797000
        }
      ]
    }
  ]
}

כדי לזהות כל נתיב בתוצאה, משתמשים באינדקס של נקודת המוצא ונקודת היעד כדי למצוא את הערך RouteMatrixItem המתאים במערך הדו-ממדי. לדוגמה, הרכיב RouteMatrixItem שמתאר את המסלול שמחושב מנקודת המוצא באינדקס 1 ועד ליעד באינדקס 0 בבקשה יהיה ברכיב השני במערך RouteMatrix.rows וברכיב הראשון במערך RouteMatrixRow.items.

קטע הקוד הבא מראה איך לזהות את RouteMatrixItem כדי למצוא את המסלול בין נקודת מוצא ליעד ספציפיים: 

// Find the route for origin 'x' and destination 'y'.
const {matrix} = await RouteMatrix.computeRouteMatrix(request);
const myRouteMatrixItem = matrix.rows[x].items[y];

בחירת שדות להחזרה

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

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

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

fields: ['durationMillis', 'distanceMeters', 'condition'],

קובעים באילו מסכות שדות להשתמש

כך קובעים באילו שדות רוצים להשתמש ויוצרים את מסכות השדות עבורם:

  1. שליחת בקשה לכל השדות באמצעות מסכת שדות של ['*'].
  2. מעיינים בהיררכיה של השדות בכיתה RouteMatrixItem כדי למצוא את השדות הרצויים.

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

    topLevelField[.secondLevelField][.thirdLevelField][...]

לדוגמה, עבור ה-RouteMatrixItem הזה:

  "travelAdvisory": {
    "fuelConsumptionMicroliters": 0,
    "tollInfo": {
      "estimatedPrices": [
        {
          "currencyCode": "USD",
          "units": 4,
          "nanos": 400000000
        }
      ]
    }
  },

אם רוצים להחזיר רק את השדה tollInfo עבור RouteMatrixItem, מסכת השדות תהיה כזו:

fields: ['travelAdvisory.tollInfo']

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

fields: ['travelAdvisory.fuelConsumptionMicroliters']

אם רוצים לבקש את שניהם, מסכת השדות תהיה:

fields: ['travelAdvisory.fuelConsumptionMicroliters', 'travelAdvisory.tollInfo']

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

fields: ['travelAdvisory']