導航・ Routes Matrix

Routes Matrix

給一組起點與一組終點，回傳每一個配對的行車距離與預估時間。派車、外送與物流系統常用它來計算多台車對多個訂單的距離矩陣，或是找出最近的車輛。

看 API 文件看 Routes

車種: 7
回傳: N × M
請求次數: 1

青色是起點、琥珀色是終點，連線代表每一組要計算的配對

多組配對一次算完

3 個起點 × 4 個終點 = 12 組配對，一次請求全部回傳。下面左邊是配對關係，右邊是回傳的表；每一格的距離與時間都是實際規劃出來的，不是示意數字。

3 起點 × 4 終點 = 12 組配對一次請求

起點＼終點	松山機場	公館	西門町	內湖
中山	4.9 公里13 分鐘	6.2 公里16 分鐘	2.4 公里7 分鐘	11.2 公里17 分鐘
市府	4.8 公里13 分鐘	4.4 公里11 分鐘	6.9 公里18 分鐘	6.3 公里12 分鐘
萬華	11.7 公里21 分鐘	6.6 公里17 分鐘	2.0 公里7 分鐘	14.5 公里21 分鐘

每一格都是實際規劃出來的距離與時間；連線為配對關係示意。

起訖點用 lat,lon|lat,lon 的格式帶入，回應是 rows[].elements[]，順序與請求一致。第 i 列第 j 欄就是第 i 個起點到第 j 個終點。每一格另有 status，兩點之間無法通行時可以個別判斷。

為什麼不逐一呼叫

12 組配對如果各打一次路線規劃，就是 12 次請求。點位一多成長得很快，5 台車對 20 個訂單就是 100 次。

逐一呼叫 Direction每組配對各一次

12 次請求

Distance Matrix一次帶入全部起訖點

1 次請求

同一組 3 起點 × 4 終點。方塊代表一次請求，長條代表等待往返的時間。

請求數從 N×M 降到 1，往返延遲不再累加。
計費單位是一次請求，不是 N×M 次。
只要距離與時間、不需要路線幾何時，回傳量小得多。

反過來說，如果你需要的是「畫在圖上的那條線」與逐段轉向指示，那是 Routes 的工作。兩支是互補的，不是替代。

車種

vehicle 決定用哪一種車輛的條件來算。同一組起訖點換一個值，走的路網就不一樣 —— 大型車有大型車不能走的路段，行人與自行車走的又是另一套路網，算出來的距離與時間自然跟著變。

一般車輛

0汽車（預設）
1一般機車
2重機150cc 以上

大型車

3貨車3.5–6.5 噸
4大貨車6.5 噸以上

人力

5行人
6自行車

路網、街廓與限行路段皆為示意。實際路徑與時間依當地路況與道路限制而定。

avoid 可以再指定要避開國道（highways）或收費路段（tolls），兩者以 | 串接。

進階版差異

需要把即時路況納入計算、或有額外的路線限制時，改用 Distance Matrix Advanced。

項目	Distance Matrix	Distance Matrix Advanced
即時路況	不納入	納入計算
路線限制	避開國道／收費路段	另支援額外的路線條件

串接 API

REST 端點是 GET /maps/api/DistanceMatrix。起訖點各自用 「|」 串起來，一次帶進去。

curl -sS -G "https://kwmap.localking.com.tw/maps/api/DistanceMatrix" \
  --data-urlencode "Key=<your-key>" \
  --data-urlencode "Origins=25.0525,121.5203|25.0336,121.5645|25.0333,121.4998" \
  --data-urlencode "Destinations=25.0616,121.5520|25.0155,121.5343|25.0424,121.5074" \
  --data-urlencode "Vehicle=0" \
  -H "Ocp-Apim-Subscription-Key: <subscription-key>"

完整參數與回應結構見 API 文件。