計算路徑矩陣

透過呼叫 computeRouteMatrix 方法 (REST) 或串流 ComputeRouteMatrix 方法 (gRPC),使用 Routes API 計算多個起點和終點的路線距離和持續時間。

假設有起點和目的地清單,此方法會計算路線起點起點,然後計算各起點終點的距離和所需時間。

要求限制

Compute Route Matrix 方法會強制執行下列要求限制:

  • 元素數量 (來源數量 × 目的地數量) 不得超過 625 個。

  • 如果指定 TRAFFIC_AWARE_OPTIMAL,元素數量不得超過 100。如要進一步瞭解 TRAFFIC_AWARE_OPTIMAL,請參閱「設定品質與延遲」。

  • 使用地點 ID 最多可以指定 50 個路線控點 (起點 + 目的地)。

回應錯誤

Compute 路徑矩陣方法的其中一項功能是可以傳回整個回應或個別回應元素。例如,如果要求的格式錯誤 (例如,其從零開始),則整個回應會包含錯誤。

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

串流結果

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 路徑和 Compute 路徑矩陣。