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

מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

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

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

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

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

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

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

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

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

תוצאות של gRPC Stream

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

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

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

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

דוגמה ל-HTTP

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

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

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

  • כדי לציין אילו שדות של התגובה (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.