瀏覽全部文件

貿易數據 API 參考

依夥伴國與 HS 產品逐月讀取貨物貿易資料:Narwhal 已收錄該國海關或統計機構資料的國家,取自該機構;其餘國家取自 UN Comtrade 或其他國家的申報。

概覽

貿易數據 API 依夥伴國與產品回傳貨物貿易資料,一次一個月。一列資料是某個月的一個貿易流向(出口或進口),含一個夥伴國或一項產品,以及以貨幣整單位表示的金額。產品依調和制度(HS)的 2、4 與 6 位碼劃分。歷史資料自 2010 年 1 月起,前提是來源有發布。本 API 僅涵蓋貨物。

數字來自申報國的海關或統計機構(Narwhal 已收錄者);涵蓋清單 181 個國家中的其餘國家,則來自 UN Comtrade 或其他國家的申報。每個回應都會說明由哪個來源提供。各國由哪個來源提供資料,請見「貿易國家」頁面。

共有七條路由可供呼叫,全都位於 /v1/trade 之下,每條路由同時也是一個 MCP 工具,參數與回應皆相同。每個請求都在 Authorization: Bearer 標頭中帶入金鑰,與 Narwhal 其他部分相同。

路由

路由MCP 工具回傳內容
GET /v1/trade/{country}/partnerstrade_get_partners單一國家依夥伴國劃分的進出口。
GET /v1/trade/{country}/productstrade_get_products單一國家依 HS 產品劃分的進出口,可為 2、4 或 6 位碼。
GET /v1/trade/{country}/products/{hs}trade_get_product單一國家在某一 HS 代碼上與所有夥伴國的貿易。
GET /v1/trade/flowstrade_get_flows針對多個申報國、夥伴國與章的開放式查詢。
GET /v1/trade/coveragetrade_get_coverage各國由哪個來源提供資料,以及已收錄的月份。免費。
GET /v1/trade/hs-codestrade_list_hs_codes依名稱、層級或上層代碼搜尋或列出 HS 代碼。
GET /v1/trade/hs-codes/{code}trade_get_hs_code單一 HS 代碼及其上層與下層代碼。

每條路由都有專屬頁面,列出所有參數、一個附有實際回應的可運作請求,以及所有錯誤。

來源

每個回應只來自一個來源,並於 basis 與 source 中標明。未帶 basis 的請求,會依此順序採用第一個有資料列的來源。同一個回應絕不混用不同來源,而 basis 可依名稱指定單一來源。

basis來源說明達到
own該國自有的海關或統計機構該機構自己發布的數字,以其本身的貨幣表示。夥伴國,以及該機構提供時的 2、4 與 6 位碼產品
third_partyUN Comtrade該國向聯合國提交的月度申報,並標明來源。僅夥伴國總額
partner_reported其他國家的海關申報其他國家對該國的申報,並將流向對調:它們從該國的進口即為該國的出口。這是另一種衡量方式,絕非官方數字。夥伴國,以及 2 位碼產品

其他國家的申報,只有在至少 200 個申報國有關於該國的資料列時,才會排在 UN Comtrade 之前;這超過 Narwhal 所收錄的數量,因此它們排在最後。依產品查詢時,UN Comtrade 沒有任何資料,所以順序是 own,然後是 partner_reported。夥伴國申報回應沒有官方總額,不接受 top、share、ytd 或 change,且最多涵蓋 12 個月。GET /v1/trade/coverage 會顯示 answers_with,即目前為各國提供資料的來源。

各國由哪個來源提供資料: 貿易國家。

貨幣

金額為 currency 所示貨幣的整單位,以十進位字串表示。預設為來源發布時使用的貨幣。currency=USD 會以該月每日匯率的平均值換算各月,並在 fx 中列出各月使用的匯率,在 calculated 中標明已換算的欄位。開放式查詢路由會在每一列標明貨幣,因為各申報國以不同貨幣發布。

分頁

limit 設定單頁最多的資料列數,範圍為 1 至 1000。在夥伴國、產品、單一產品與開放式查詢路由預設為 500,在 GET /v1/trade/hs-codes 預設為 100。符合條件的資料列較多時,next_cursor 會帶有下一頁的游標:將它作為 cursor 傳入,其他參數保持不變。來自不同請求的游標會回傳 400 invalid_cursor。total 計算所有頁面中符合條件的資料列。MCP 工具單次結果最多回傳 200 列。

價格

貿易數據呼叫每 1,000 次收費 $2。回傳至少一列資料的請求算一次呼叫,較長回應的每一頁也各算一次呼叫。沒有資料列的回應免費,所有錯誤免費,涵蓋範圍路由也免費。額度與儲值請見價格頁。

錯誤

錯誤使用共用的問題格式,並附有 request_id。每個路由頁面都列出該路由可能回傳的錯誤。以下是全部錯誤。

狀態代碼發生時機
401, 402, 429unauthorized, insufficient_credits, rate_limited缺少或無效的金鑰、餘額低於該次呼叫的價格,或每分鐘請求過多。請見「錯誤與額度」。
400invalid_query缺少參數、參數格式錯誤或超出允許值:例如 start=2026-13、start 晚於 end、ytd 與 start 一併傳入,或傳入了 as_of 或 version(這些路由提供目前已收錄的資料)。另外,對夥伴國申報回應要求 top、share、ytd 或 change 時也是。
400invalid_cursor此游標不是該請求所回傳的游標,或其後有其他參數已變更。
400unknown_partner在所查詢的月份中,partner 不是該國的夥伴國,例如 ZZZ is not a partner of GBR.。
400range_too_largetop、share、ytd 或 change 涵蓋超過 12 個月、夥伴國申報回應涵蓋超過 12 個月,或產品回應(任何層級,2、4 或 6 位碼)在未帶 hs 或 partner 時涵蓋超過 12 個已收錄月份。開放式查詢會以 invalid_query 拒絕超過 12 個月的區間。
404hs_code_not_foundHS 版本中沒有此代碼。
404country_not_coveredNarwhal 在任何來源中都沒有該國的貿易資料列。
404period_not_published所查詢的月份未收錄(No trade rows for 2026-10.),或 ytd 或 change 所需的某個月份缺漏。
404basis_not_available所指定的來源,或順序中的每個來源,都沒有符合該問題的資料。detail 會說明原因:例如該國自有機構僅提供夥伴國總額而無產品,或夥伴國申報回應僅達章(2 位碼),或泰國自有機構僅以 4 位碼保存卻被要求 6 位碼。請見涵蓋範圍路由。
404rate_not_available要求了 currency=USD,但某個月份沒有匯率。
503upstream_unavailable匯率來源無法回應。這會影響 currency=USD,以及需要換算的夥伴國申報回應。請稍後再試。
503trade_data_unavailable目前無法讀取產品檔案。請稍後再試。

API 錯誤 處理:錯誤碼、額度與重試 · 貿易數據 API 參考 · 貿易國家

MCP 工具

每條路由都是各自獨立的 MCP 工具,參數與回應皆相同。MCP 工具單次結果最多回傳 200 列,因此請以 cursor 分頁。這些工具如下:

trade_list_hs_codestrade_get_hs_codetrade_get_coveragetrade_get_partnerstrade_get_productstrade_get_producttrade_get_flows

此頁面對你有幫助嗎?