貿易數據 API 參考
依夥伴國與 HS 產品逐月讀取貨物貿易資料:Narwhal 已收錄該國海關或統計機構資料的國家,取自該機構;其餘國家取自 UN Comtrade 或其他國家的申報。
概覽
貿易數據 API 依夥伴國與產品回傳貨物貿易資料,一次一個月。一列資料是某個月的一個貿易流向(出口或進口),含一個夥伴國或一項產品,以及以貨幣整單位表示的金額。產品依調和制度(HS)的 2、4 與 6 位碼劃分。歷史資料自 2010 年 1 月起,前提是來源有發布。本 API 僅涵蓋貨物。
數字來自申報國的海關或統計機構(Narwhal 已收錄者);涵蓋清單 181 個國家中的其餘國家,則來自 UN Comtrade 或其他國家的申報。每個回應都會說明由哪個來源提供。各國由哪個來源提供資料,請見「貿易國家」頁面。
共有七條路由可供呼叫,全都位於 / 之下,每條路由同時也是一個 MCP 工具,參數與回應皆相同。每個請求都在 Authorization: Bearer 標頭中帶入金鑰,與 Narwhal 其他部分相同。
路由
| 路由 | MCP 工具 | 回傳內容 |
|---|---|---|
GET / | trade_ | 單一國家依夥伴國劃分的進出口。 |
GET / | trade_ | 單一國家依 HS 產品劃分的進出口,可為 2、4 或 6 位碼。 |
GET / | trade_ | 單一國家在某一 HS 代碼上與所有夥伴國的貿易。 |
GET / | trade_ | 針對多個申報國、夥伴國與章的開放式查詢。 |
GET / | trade_ | 各國由哪個來源提供資料,以及已收錄的月份。免費。 |
GET / | trade_ | 依名稱、層級或上層代碼搜尋或列出 HS 代碼。 |
GET / | trade_ | 單一 HS 代碼及其上層與下層代碼。 |
每條路由都有專屬頁面,列出所有參數、一個附有實際回應的可運作請求,以及所有錯誤。
來源
每個回應只來自一個來源,並於 basis 與 source 中標明。未帶 basis 的請求,會依此順序採用第一個有資料列的來源。同一個回應絕不混用不同來源,而 basis 可依名稱指定單一來源。
basis | 來源 | 說明 | 達到 |
|---|---|---|---|
own | 該國自有的海關或統計機構 | 該機構自己發布的數字,以其本身的貨幣表示。 | 夥伴國,以及該機構提供時的 2、4 與 6 位碼產品 |
third_ | UN Comtrade | 該國向聯合國提交的月度申報,並標明來源。 | 僅夥伴國總額 |
partner_ | 其他國家的海關申報 | 其他國家對該國的申報,並將流向對調:它們從該國的進口即為該國的出口。這是另一種衡量方式,絕非官方數字。 | 夥伴國,以及 2 位碼產品 |
其他國家的申報,只有在至少 200 個申報國有關於該國的資料列時,才會排在 UN Comtrade 之前;這超過 Narwhal 所收錄的數量,因此它們排在最後。依產品查詢時,UN Comtrade 沒有任何資料,所以順序是 own,然後是 partner_。夥伴國申報回應沒有官方總額,不接受 top、share、ytd 或 change,且最多涵蓋 12 個月。GET / 會顯示 answers_,即目前為各國提供資料的來源。
各國由哪個來源提供資料: 貿易國家。
貨幣
金額為 currency 所示貨幣的整單位,以十進位字串表示。預設為來源發布時使用的貨幣。currency=USD 會以該月每日匯率的平均值換算各月,並在 fx 中列出各月使用的匯率,在 calculated 中標明已換算的欄位。開放式查詢路由會在每一列標明貨幣,因為各申報國以不同貨幣發布。
分頁
limit 設定單頁最多的資料列數,範圍為 1 至 1000。在夥伴國、產品、單一產品與開放式查詢路由預設為 500,在 GET / 預設為 100。符合條件的資料列較多時,next_ 會帶有下一頁的游標:將它作為 cursor 傳入,其他參數保持不變。來自不同請求的游標會回傳 400 invalid_。total 計算所有頁面中符合條件的資料列。MCP 工具單次結果最多回傳 200 列。
價格
貿易數據呼叫每 1,000 次收費 $2。回傳至少一列資料的請求算一次呼叫,較長回應的每一頁也各算一次呼叫。沒有資料列的回應免費,所有錯誤免費,涵蓋範圍路由也免費。額度與儲值請見價格頁。
錯誤
錯誤使用共用的問題格式,並附有 request_。每個路由頁面都列出該路由可能回傳的錯誤。以下是全部錯誤。
| 狀態 | 代碼 | 發生時機 |
|---|---|---|
401, 402, 429 | unauthorized, insufficient_credits, rate_limited | 缺少或無效的金鑰、餘額低於該次呼叫的價格,或每分鐘請求過多。請見「錯誤與額度」。 |
400 | invalid_query | 缺少參數、參數格式錯誤或超出允許值:例如 start=2026-13、start 晚於 end、ytd 與 start 一併傳入,或傳入了 as_ 或 version(這些路由提供目前已收錄的資料)。另外,對夥伴國申報回應要求 top、share、ytd 或 change 時也是。 |
400 | invalid_cursor | 此游標不是該請求所回傳的游標,或其後有其他參數已變更。 |
400 | unknown_partner | 在所查詢的月份中,partner 不是該國的夥伴國,例如 ZZZ is not a partner of GBR.。 |
400 | range_too_large | top、share、ytd 或 change 涵蓋超過 12 個月、夥伴國申報回應涵蓋超過 12 個月,或產品回應(任何層級,2、4 或 6 位碼)在未帶 hs 或 partner 時涵蓋超過 12 個已收錄月份。開放式查詢會以 invalid_ 拒絕超過 12 個月的區間。 |
404 | hs_code_not_found | HS 版本中沒有此代碼。 |
404 | country_not_covered | Narwhal 在任何來源中都沒有該國的貿易資料列。 |
404 | period_not_published | 所查詢的月份未收錄(No trade rows for 2026-10.),或 ytd 或 change 所需的某個月份缺漏。 |
404 | basis_not_available | 所指定的來源,或順序中的每個來源,都沒有符合該問題的資料。detail 會說明原因:例如該國自有機構僅提供夥伴國總額而無產品,或夥伴國申報回應僅達章(2 位碼),或泰國自有機構僅以 4 位碼保存卻被要求 6 位碼。請見涵蓋範圍路由。 |
404 | rate_not_available | 要求了 currency=USD,但某個月份沒有匯率。 |
503 | upstream_unavailable | 匯率來源無法回應。這會影響 currency=USD,以及需要換算的夥伴國申報回應。請稍後再試。 |
503 | trade_data_unavailable | 目前無法讀取產品檔案。請稍後再試。 |
MCP 工具
每條路由都是各自獨立的 MCP 工具,參數與回應皆相同。MCP 工具單次結果最多回傳 200 列,因此請以 cursor 分頁。這些工具如下:
trade_ list_ hs_ codestrade_ get_ hs_ codetrade_ get_ coveragetrade_ get_ partnerstrade_ get_ productstrade_ get_ producttrade_ get_ flows此頁面對你有幫助嗎?