取得路徑矩陣

透過呼叫 computeRouteMatrix 方法 (REST) 或串流 ComputeRouteMatrix 方法 (gRPC),使用 Routes API 計算多個起點和目的地的路徑距離和所需時間。

假設已知了起點和目的地清單,這個方法會計算從每個起點開始,最後到每個目的地結束的路線距離和所需時間。

取得大眾運輸路線矩陣

您也可以在大眾運輸上計算路線矩陣。如需範例,請參閱取得大眾運輸的路線矩陣

要求限制

Compute Route Matrix 方法會針對使用地址或 placeID 的路線點和元素強制執行下列要求限制。元素是路線矩陣中每個起點與目的地之間的路線,因此元素數量是指目的地「時間」數。舉例來說,假設您有 10 個起點和 10 個目的地,就會有 100 個元素:

  • 如果路徑不是 TRANSIT 路徑,元素數量不得超過 625 個。

  • 如果您指定 TRANSIT 路徑,元素數量不得超過 100 個。

  • 如果指定 TRAFFIC_AWARE_OPTIMAL,元素數量不得超過 100 個。如要進一步瞭解 TRAFFIC_AWARE_OPTIMAL,請參閱「指定如何納入車流量資料,以及是否要納入流量資料」。

  • 如果您使用地址或地點 ID 指定出發地或目的地,就能指定最多 50 個。

回應錯誤

Compute Route Matrix 方法的其中一個功能是,系統可能會針對整個回應或個別回應元素傳回錯誤。例如,如果要求格式錯誤 (例如沒有來源),整個回應就會包含錯誤。

不過,如果回應中的部分元素發生錯誤 (例如無法針對一個起點與目的地的組合計算路徑),則只有受錯誤影響的元素會傳回錯誤代碼。

gRPC 串流結果

ComputeRouteMatrix gRPC 方法會擷取起點和目的地清單,並傳回含有每個起點與目的地組合路徑資訊的串流。由於結果會以串流的形式傳回,因此您不必等到系統計算所有可能的路徑組合後,就可以開始處理結果。

串流傳回的元素不保證會依任何順序傳回。因此,每個回應元素都包含 origin_indexdestination_index。針對要求指定的起點和目的地,特定元素的路線起點相當於 origins[origin_index],而路線目的地則相當於 destinations[destination_index]。這些陣列不會建立索引。請務必儲存出發地和目的地清單順序。

計算路徑矩陣範例

在 HTTP 要求中使用 computeRouteMatrix 方法,計算路徑矩陣。

HTTP 範例

以下範例顯示 computeRouteMatrix HTTP 要求。在這個範例中,您:

  • 指定兩個起點和兩個目的地路線控點的陣列。這個方法會計算從每個起點到每個目的地的路線,因此回應包含四個路徑。

    在陣列中,第一個元素位於 0 的索引處,第二個元素為索引 1,依此類推。

  • 加入回應欄位遮罩,以指定要傳回的回應 (REST) 或 ComputeRoutesResponse (gRPC) 欄位。在這個範例中,請設定要求,針對每條路線傳回 originIndexdestinationIndexdurationdistanceMetersstatuscondition。詳情請參閱「選擇要傳回的欄位」。

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'

回應包含所有起點與目的地路線控點的組合可能的四個可能路線。

使用 originIndexdestinationIndex 回應欄位識別回應中的每個路徑。舉例來說,回應中的 originIndex 為 1 對應到在要求中 origins 陣列的索引 1 所計算的路線。

[
    {
        "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。