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

מפתחים באזור הכלכלי האירופי (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.