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

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

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

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

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

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

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

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

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

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

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

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

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

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

תוצאות של gRPC Stream

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

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

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

כדי לחשב מטריצה של מסלולים, משתמשים ב-method‏ computeRouteMatrix בבקשת HTTP.

דוגמה ל-HTTP

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

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

    במערך, הרכיב הראשון נמצא באינדקס 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 Matrix.