基本介紹

勤崴 OpenAPI 的入口說明：服務清單、金鑰怎麼帶與錯誤處理。

這一區是勤崴 OpenAPI 的文件：用 HTTP 直接呼叫的地點搜尋、路徑規劃與加值服務。端點與參數即時取自 API 管理平台（APIM），與 gateway 實際受理的內容同步。

服務清單

服務	說明	端點數
Places API	搜尋地點、取得詳細的位置資訊，以及依座標與半徑查詢站點。	8
Routes API	為各種交通模式計算最佳化路線、距離矩陣與路網貼附。	5

清單會依登入狀態有所變化：登入後如果有使用中的訂閱，API 那一區只列出這個帳號訂得到的服務；未登入則列出所有已發布的服務，要試打才需要金鑰。

用的是同一把訂閱金鑰，但要填在兩個位置，且皆為必填：

位置	形式	誰在看
標頭 `Ocp-Apim-Subscription-Key`	`Ocp-Apim-Subscription-Key: <金鑰>`（也接受查詢參數 `subscription-key`）	APIM —— 認證、計量與流量限制
查詢參數 `Key`	`?Key=<金鑰>`	後端服務 —— 授權與加值資料範圍

金鑰來自開發者平台的訂閱方案，一組方案有主要／次要兩把，都可以自行重新產生。線上試打的面板在你選好金鑰之後會同時填好這兩處，不必貼兩次。

HTTP 狀態碼由 APIM 與後端服務共同決定，常見的幾種：

狀態碼	常見原因
`200`	受理成功。內容裡仍可能有 `status` 欄位表示查無資料，要一起判斷。
`401`	訂閱金鑰缺漏或無效。
`403`	訂閱金鑰有效但沒有這支 API 的權限，或服務金鑰未開通。
`429`	超出訂閱方案的流量限制。
`5xx`	後端服務異常，可重試；持續發生請聯絡窗口。

接下來：線上試打可以不寫任何程式碼就先送一次請求，確認參數與金鑰都對了再回去寫程式。