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

תוכלו להשתמש ב-Routes API כדי לחשב את המרחק ומשך הזמן של מסלול במספר מקורות ויעדים, באמצעות קריאה לשיטה computeRouteMatrix (REST) או ל-method ComputeRouteMatrix (gRPC).

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

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

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

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

ה-methods של מטריצת המסלול של Compute אוכפות את מגבלות הבקשות הבאות לציוני דרך באמצעות כתובות או מזהי PlaceID ולרכיבים. הרכיבים הם המסלולים בין כל מוצא ויעד במטריצת מסלולים, כך שמספר הרכיבים הוא מספר הפעמים של המוצא. לדוגמה, אם יש לכם 10 מקורות ו-10 יעדים, יש לכם 100 רכיבים:

  • מספר הרכיבים לא יכול לחרוג מ-625 למסלולים שהם לא נתיבי TRANSIT.

  • אם מציינים נתיב TRANSIT, מספר הרכיבים לא יכול לחרוג מ-100.

  • אם מציינים את TRAFFIC_AWARE_OPTIMAL, מספר הרכיבים לא יכול להיות גדול מ-100. מידע נוסף על TRAFFIC_AWARE_OPTIMAL זמין במאמר איך מציינים איך ואם לכלול נתוני תנועה.

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

שגיאות בתשובה

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

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

תוצאות של עדכוני gRPC

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

אין ערובה לכך שהרכיבים שחוזרים מהסטרימינג יוחזרו בכל סדר שהוא. לכן, כל רכיב תגובה מכיל origin_index ו-destination_index. למקורות וליעדים שצוינו בבקשה, נקודת המוצא של המסלול שווה ל-origins[origin_index] לרכיב נתון ויעד המסלול שווה ל-destinations[destination_index]. המערכים האלה נוספים אפס באינדקס. חשוב לאחסן את ההזמנות של רשימות המקור והיעד.

דוגמאות של מטריצת מסלול

משתמשים ב-method computeRouteMatrix בבקשת HTTP כדי לחשב מטריצת נתיב.

דוגמה ל-HTTP

הדוגמה הבאה מציגה בקשת HTTP computeRouteMatrix. בדוגמה הזו:

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

    במערך, הרכיב הראשון נמצא באינדקס של 0, השני הוא אינדקס 1 וכן הלאה.

  • מוסיפים אנונימיזציה של שדות תשובה כדי לציין אילו שדות ב-response (REST) או ב-ComputeRoutesResponse (gRPC) שיוחזרו. בדוגמה הזו, מגדירים את הבקשה שתחזיר את הערכים originIndex, destinationIndex, duration, distanceMeters, status ו-condition לכל מסלול. מידע נוסף זמין במאמר בחירת שדות להחזרה.

curl -X POST -d '{
  "origins": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420761,
            "longitude": -122.081356
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.403184,
            "longitude": -122.097371
          }
        }
      },
      "routeModifiers": { "avoid_ferries": true}
    }
  ],
  "destinations": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420999,
            "longitude": -122.086894
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.383047,
            "longitude": -122.044651
          }
        }
      }
    }
  ],
  "travelMode": "DRIVE",
  "routingPreference": "TRAFFIC_AWARE"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H 'X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status,condition' \
'https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix'

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

מאתרים כל נתיב בתשובה באמצעות שדות התשובה originIndex ו-destinationIndex. לדוגמה, הערך originIndex של 1 בתשובה תואם למסלול שמחושב מנקודת הציון באינדקס 1 של מערך origins בבקשה.

[
    {
        "originIndex": 0,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 822,
        "duration": "160s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 0,
        "status": {},
        "distanceMeters": 2919,
        "duration": "361s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 1,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 5598,
        "duration": "402s",
        "condition": "ROUTE_EXISTS"
    },
    {
        "originIndex": 0,
        "destinationIndex": 1,
        "status": {},
        "distanceMeters": 7259,
        "duration": "712s",
        "condition": "ROUTE_EXISTS"
    }
]

דוגמאות ל-gRPC

לדוגמה, בקשות ל-gRPC, אפשר לעיין בדוגמאות בבקשה לדוגמה ל-gRPC. בדוגמה של Java בדף הזה מופיעה קריאה גם ל-Compute Routes וגם למטריצת Compute Route.