Routes API 總覽

Routes API 是一項接受 HTTPS 要求的服務,會傳回兩個位置之間的理想路線,或不同起點和目的地位置之間的路線矩陣距離與交通時間。

使用 Routes API 的好處

透過 Routes API,您可以依據交通詳細資料、最新路況與路況以及路線偏好設定,取得準確的路線和行程資訊:

  • 各種交通方式的類型和功能

  • 車輛的方向

  • 要上車或下車的道路側邊

  • 路況與道路封閉

  • 安全疑慮,例如避開危險區域或提供安全的上車區域

  • 在路線規劃需求的延遲時間、品質和成本之間取得平衡,選用功能包括過路費、行程中繼資料 (例如時間和距離),以及燃油效率

您也可以決定最有效率的路徑分派排程,例如:

  • 如何指派一組工作站來領取一系列包裹的最佳方式

  • 找出最合適的倉庫,將包裹寄到最終目的地

Routes API 提供哪些功能?

您可以使用 Routes API 取得兩種主要類別的轉送資訊:

  • 從某個地點的路徑至單一或多個目的地

  • 多個起點和終點之間的可能路線矩陣

取得單一或多個目的地的路線

使用 Routes API Compute Routes 方法,即可計算位置之間:

  • 取得不同交通方式的路線,以及單一或多個目的地的路線:

    • 交通方式,包括大眾運輸、開車、機車、步行或單車。

    • 可以進行最佳化的一系列路線控點,以最有效率的方式移動這些路線點。

  • 多種指定起點、目的地和路線控點的方法

    • 文字字串。例如:「Chicago, IL」、「Darwin, NT, Australia」、「1800 Amphitheatre Parkway, Mountain View, CA 94043」或「CWF6+FWX Mountain View, California」

    • 地點 ID

    • 經緯度座標 (可選擇加上車輛方向)

  • 根據需求和目標調整路線選項

  • 使用欄位遮罩僅要求所需資料以控制延遲和品質,這有助於避免不必要的處理時間,並產生較高的要求費率。詳情請參閱選擇要傳回的資訊

取得可能路徑的矩陣

Routes API Compute Route Matrix 方法針對多個起點和終點之間的建議路線提供矩陣資訊 (包括距離和預估抵達時間),協助您根據業務需求選擇最合適的起點和目的地。您可以要求取得下列類型的距離資料:

  • 所選交通方式的距離

  • 距離 (公里或英里)

  • 預估交通時間

透過距離資料,您可以決定在多個可能起點與目的地之間轉送乘客、貨物或員工最有效率的方法。

您可以在計算整個矩陣之前,先串流回應元素,進而縮短回應延遲時間。

您可以為每個伺服器端要求指定多個起點和目的地,將起點數乘以目的地數量 (上限為 625)。

Routes API 的運作方式

Routes API 有兩種方法:ComputeRouteComputeRouteMatrix

ComputeRoute

Routes API ComputeRoute 方法接受 HTTP POST 要求,其中包含內含要求詳細資料的 JSON 要求主體。必填是 origin、destination、travelMode 和欄位遮罩,可指定要傳回的欄位。

範例

curl -X POST -d '{
    "origin": {
      "address": "1800 Amphitheatre Parkway, Mountain View, CA 94043"
    },
    "destination": {
      "address": "Sloat Blvd &, Upper Great Hwy, San Francisco, CA 94132"
    },
  "travelMode": "DRIVE"
  }' \
  -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: YOUR_API_KEY' \
  -H 'X-Goog-FieldMask: routes.duration,routes.distanceMeters' \
  'https://routes.googleapis.com/directions/v2:computeRoutes'

服務接著會計算要求的路徑,並傳回您要求的欄位。

ComputeRouteMatrix

Routes API ComputeRouteMatrix 接受 HTTP POST 要求,其中包含內含要求詳細資料的 JSON 要求主體。必須提供至少一個來源、兩個以上的目的地、travelMode,以及欄位遮罩以指定要傳回的欄位。

範例

curl -X POST -d '{
  "origins": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420761,
            "longitude": -122.081356
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.403184,
            "longitude": -122.097371
          }
        }
      }
    }
  ],
  "destinations": [
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.420999,
            "longitude": -122.086894
          }
        }
      }
    },
    {
      "waypoint": {
        "location": {
          "latLng": {
            "latitude": 37.383047,
            "longitude": -122.044651
          }
        }
      }
    }
  ],
  "travelMode": "DRIVE"
}' \
-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'

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

資源

下表摘要說明透過 Routes API 使用的資源,以及其傳回的資料。

資料資源 傳回的資料 傳回格式
ComputeRoute 傳迴路線的路線、路段和步驟 (如有需要)。 JSON
ComputeRouteMatrix 傳回從一個起點到一個目的地路線控點的路線陣列。

如何使用 Routes API

1 做好準備 先從「設定 Google Cloud 專案」開始,並按照當中的指示操作。
2 計算路線並查看回應 詳情請參閱「取得路徑」和「查看路線回應」。
3 計算路徑矩陣並查看回應 詳情請參閱「取得路徑矩陣」和「查看路線矩陣回應」。

可用的用戶端程式庫

如需 Routes API 的可用用戶端程式庫清單,請參閱「用戶端程式庫」。

後續步驟