依產品劃分的貿易 API 參考
讀取一個國家依 HS 產品(2、4 或 6 位碼)劃分的進出口,每個代碼、每個月份與每個流向各一列,並附上各代碼的名稱。
概覽
GET /
GET / 回傳一個國家依產品劃分的貨物貿易:每個 HS 代碼、每個月份與每個流向各一列,並附上代碼名稱。level 決定層級:2 為章(預設值),4 為品目,6 為子目。未帶 start 與 end 時,回應為已收錄的最新月份。
partner 將回應限定於單一夥伴國,hs 則限定於以這些數字開頭的代碼。用它來了解一個國家賣出與買進什麼。單一產品對所有夥伴國請使用單一產品路由。
對於自有機構僅提供夥伴國總額的國家(加拿大、墨西哥與澳大利亞),產品路由會以其他國家的申報回應章,標示為 partner_,而品目與子目則回傳 404 basis_。MCP 工具為 trade_,參數相同。
請求
英國在 2026 年 6 月三大出口章及其占比,以及實際回應:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/products?start=2026-06&end=2026-06&flow=export&top=3&share=true"{
"country": "GBR",
"basis": "own",
"source": "HM Revenue & Customs",
"reporters_included": null,
"note": null,
"coverage": "full",
"partner_coverage": "all",
"scope": "goods",
"currency": "GBP",
"classification": "HS",
"edition": "2022",
"edition_basis": "inferred_from_year",
"valuation_basis": "not_stated",
"trade_system": "not_stated",
"partner_basis": "not_stated",
"trade_scope": "all_partners",
"latest_period": "2026-09",
"total_basis": "customs",
"totals": [
{
"period": "2026-06",
"flow": "export",
"official_total": "37649508686",
"sum_of_rows": "37649508686"
}
],
"fx": null,
"calculated": [
"sum_of_rows",
"rank",
"share"
],
"total": 3,
"partner": null,
"rows": [
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "7115661421",
"net_weight_kg": "195511199",
"rank": 1,
"share": "0.188997",
"change": null,
"product_code": "84",
"product_level": 2,
"product_label": "NUCLEAR REACTORS, BOILERS, MACHINERY AND MECHANICAL APPLIANCES; PARTS THEREOF",
"edition": "2022"
},
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "7044982137",
"net_weight_kg": "1706268",
"rank": 2,
"share": "0.187120",
"change": null,
"product_code": "71",
"product_level": 2,
"product_label": "NATURAL OR CULTURED PEARLS, PRECIOUS OR SEMI-PRECIOUS STONES, PRECIOUS METALS, METALS CLAD WITH PRECIOUS METAL, AND ARTICLES THEREOF; IMITATION JEWELLERY; COIN",
"edition": "2022"
}
],
"next_cursor": null
}此頁顯示三列中的前兩列。share 是以 1 為基準的比例:第 84 章占該月出口的 0.189134。partner 為 null,因為資料列並未限定於單一夥伴國。
參數
| 參數 | 位置 | 類型 | 必填 | 預設值 | 允許值與意義 |
|---|---|---|---|---|---|
country | path | 字串 | 是 | 無 | 申報國的 ISO 3166-1 alpha-3 代碼,使用大寫,例如 GBR。不是國家的代碼會回傳 400。沒有數字的國家會回傳 404 country_。 |
level | query | 整數 | 否 | 2 | 2(章)、4(品目)或 6(子目)。其他任何值會回傳 400。泰國以 4 位碼保存,因此對泰國使用 6 會回傳 404 basis_。 |
partner | query | 字串 | 否 | 所有夥伴國 | 僅限與此夥伴國的貿易(ISO 3166-1 alpha-3,使用大寫)。不是該國夥伴國的代碼會回傳 400 unknown_。 |
flow | query | 字串 | 否 | 兩個流向 | export 或 import。 |
start | query | 字串,YYYY-MM | 否 | 已收錄的最新月份 | 起始月份,含該月。帶有 start 而無 end 時,回應會涵蓋至已收錄的最新月份。start 晚於 end 會回傳 400。 |
end | query | 字串,YYYY-MM | 否 | 已收錄的最新月份 | 結束月份,含該月。僅帶 end 時,回應為不晚於該月的最新已收錄月份。 |
hs | query | 字串,1 至 6 位數字 | 否 | 所有代碼 | 僅限以這些數字開頭的代碼。長度超過 level 會回傳 400。 |
basis | query | 字串 | 否 | 已收錄的最佳來源 | own、third_ 或 partner_。依名稱指定單一來源,並略過順序。對該問題沒有資料的來源會回傳 404 basis_。 |
currency | query | 字串 | 否 | 來源自己的貨幣 | USD。以各月的每日平均匯率換算。 |
top | query | 整數 | 否 | 所有資料列 | 1 至 1000。每個月份與流向保留金額最大的 N 個產品資料列,依金額排名,金額相同時以產品代碼決定順序,並為每列加上 rank。為計算所得。最多涵蓋 12 個月。不適用於夥伴國申報回應。 |
share | query | 布林值 | 否 | false | true 會為每一列加上 share:其金額除以同月份、同流向所有產品資料列的加總,以 1 為基準的小數表示,保留 6 位小數。為計算所得。最多涵蓋 12 個月。不適用於夥伴國申報回應。 |
ytd | query | 布林值 | 否 | false | true 會將已儲存月份中自 1 月至 end(預設:最新月份)的資料加總,且 period_ 為 year_。請傳入 end,不要傳入 start:帶有 start 的請求會回傳 400。缺少月份會回傳 404 period_。為計算所得。不適用於夥伴國申報回應。 |
change | query | 布林值 | 否 | false | true 會為每一列加上 change:去年同月(或年初至今)的資料、兩者的差額,以及雙方的發布狀態。缺少前一年的月份會回傳 404 period_。為計算所得。最多涵蓋 12 個月。不適用於夥伴國申報回應。 |
limit | query | 整數 | 否 | 500 | 1 至 1000。單頁最多的資料列數。 |
cursor | query | 字串 | 否 | 無 | 上一頁的 next_,其他所有參數保持不變。 |
回應
回應包含夥伴國路由的欄位(列於該頁面),另外多一個與夥伴國篩選有關的欄位。
| 欄位 | 含義 |
|---|---|
country | 回應所屬申報國的 ISO 3166-1 alpha-3 代碼。 |
partner | 資料列所限定的夥伴國,未傳入 partner 時為 null。 |
basis | 提供資料的來源:own、third_(UN Comtrade)或 partner_。 |
source | 發布機構,例如 HM Revenue & Customs、Eurostat Comext、UN Comtrade 或 Customs reports of other countries。 |
reporters_ | 搭配 partner_ 時:其申報被對調後納入回應的申報國的 count 與 countries。其他來源則為 null。 |
note | 使用這些數字前請先閱讀。夥伴國申報回應會設定此欄位,否則為 null。 |
coverage | full 或 partial。夥伴國申報回應為 partial。 |
partner_ | 列出所有夥伴國時為 all;發布機構僅列示其主要夥伴國與一列其餘合計時為 top_。夥伴國申報回應則為 null。 |
scope | goods。 |
currency | 回應中所有金額的 ISO 4217 代碼。 |
classification | HS,即調和制度(Harmonized System)。 |
edition | 當單一版本涵蓋所查詢的每個月份時,為 HS 版本(2007、2012、2017 或 2022)。月份間版本不同時為 null,此時每一列各自標明其版本。 |
edition_ | 發布機構載明版本時為 as_;由 Narwhal 依年份推算時為 inferred_。 |
valuation_ | 發布機構對貿易的計價方式,例如出口採 FOB、進口採 CIF。未說明時為 not_。 |
trade_ | 發布機構有說明時為 general 或 special;否則為 not_。 |
partner_ | 夥伴國依原產地、發貨地或目的地計算,依發布機構所述。未說明時為 not_。 |
trade_ | 數字涵蓋的範圍,例如 all_、extra_ 或 intra_。 |
latest_ | Narwhal 為此國家與來源收錄的最新月份。 |
total_ | official_ 的依據:customs、balance_ 或 eurostat_。發布機構未提供總額時為 null。 |
totals | 每個月份與流向各一項:period、flow、official_(發布機構自己的貨物總額,不存在時為 null)與 sum_(該月份與流向中,除群組資料列外所有夥伴國資料列的加總,為計算所得)。未帶 hs 時,它包含該月的整體貨物總額,即使 partner 限制了資料列也是如此。帶有 hs 時(以及在單一產品路由上),它改為包含該產品的總額:sum_ 是回應中所有頁面資料列的加總(若有指定 partner,則為該夥伴國的;top 與分頁不會截斷它),而 official_ 為 null,因為發布機構沒有列示單一產品的總額。 |
fx | 搭配 currency=USD,以及以多種貨幣呈現的夥伴國申報回應時:各月使用的匯率,附有 period、from_、to_、rate,以及平均值所含的 days。其他情況為 null。 |
calculated | Narwhal 計算出的欄位名稱,例如 sum_、rank、share、value 或 official_。 |
total | 所有頁面中符合條件的資料列數。 |
next_ | 下一頁的游標。最後一頁為 null。 |
rows 的每一項是一個月份與流向中的一個 HS 代碼。
| 欄位 | 含義 |
|---|---|
flow | export 或 import。 |
period | 月份,YYYY-MM。年初至今時為其最後一個月。 |
period_ | month 或 year_。 |
period_ | 該列涵蓋的第一天與最後一天,YYYY-MM-DD。 |
value | currency 的整單位,以十進位字串表示。 |
net_ | 淨重(公斤),發布機構有提供時才有。否則為 null。 |
rank, share, change | 與夥伴國路由相同:搭配 top、share 與 change 時有值,否則為 null。 |
product_ | HS 代碼,2、4 或 6 位碼。發布機構自己列示、不是 HS 產品的資料行會保留發布機構的代碼,例如 00 代表船舶補給品與私人託運貨物。 |
product_ | 2 代表章,4 代表品目,6 代表子目。 |
product_ | 代碼名稱。不是 HS 產品的資料行為 null。 |
edition | 該月來源的 HS 版本。各申報國使用不同版本時為 null。 |
更多範例
單一品目的子目
英國出口中品目 8517 之下的六位碼代碼,第一頁(五列):
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/GBR/products?level=6&hs=8517&start=2026-06&end=2026-06&flow=export&limit=5"{
"country": "GBR",
"basis": "own",
"source": "HM Revenue & Customs",
"reporters_included": null,
"note": null,
"coverage": "full",
"partner_coverage": "all",
"scope": "goods",
"currency": "GBP",
"classification": "HS",
"edition": "2022",
"edition_basis": "inferred_from_year",
"valuation_basis": "not_stated",
"trade_system": "not_stated",
"partner_basis": "not_stated",
"trade_scope": "all_partners",
"latest_period": "2026-09",
"total_basis": "customs",
"totals": [
{
"period": "2026-06",
"flow": "export",
"official_total": null,
"sum_of_rows": "427312411"
}
],
"fx": null,
"calculated": [
"sum_of_rows"
],
"total": 9,
"partner": null,
"rows": [
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "2578425",
"net_weight_kg": "12393",
"rank": null,
"share": null,
"change": null,
"product_code": "851711",
"product_level": 6,
"product_label": "Line telephone sets with cordless handsets",
"edition": "2022"
},
{
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"value": "105530961",
"net_weight_kg": "115108",
"rank": null,
"share": null,
"change": null,
"product_code": "851713",
"product_level": 6,
"product_label": "Smartphones for wireless networks",
"edition": "2022"
}
],
"next_cursor": "eyJiIjoiY2hhbmdlPUZhbHNlfGNvdW50cnk9R0JSfGVuZD0yMDI2LTA2fGZsb3c9ZXhwb3J0fGhzPTg1MTd8bGV2ZWw9NnxzaGFyZT1GYWxzZXxzdGFydD0yMDI2LTA2fHl0ZD1GYWxzZSIsIm8iOjV9"
}此頁顯示五列中的前兩列。total 為 9,因此 next_ 有值。totals 包含九個子目的加總,而 official_ 為 null。
僅提供夥伴國總額的國家的品目
加拿大的自有機構不提供產品資料。查詢品目會回傳 404,且免費:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/CAN/products?level=4&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"{
"type": "https://narwhalapi.com/problems/basis-not-available",
"title": "Basis not available",
"status": 404,
"detail": "Narwhal holds CAN's own partner totals only, not its products; UN Comtrade is held as partner totals only, not by product; partner-reported products are held at chapter level only (level=2). See /v1/trade/coverage.",
"code": "basis_not_available",
"request_id": "5dd0f449-8c1e-4354-9af6-d8a76a5eefdd"
}來源
每個請求由一個來源提供資料,依此順序採用第一個有資料列的來源:該國自有的海關或統計機構(basis 為 own)、該國向 UN Comtrade 提交的申報(third_,僅夥伴國總額),然後是其他國家對該國的申報,並將流向對調(partner_)。其他國家的申報,只有在至少 200 個申報國有關於該國的資料列時,才會排在 UN Comtrade 之前,這超過 Narwhal 所收錄的數量,因此它們排在最後。依產品查詢時,UN Comtrade 沒有任何資料,所以順序是 own,然後是 partner_,且 partner_ 僅達章(2 位碼)。basis 可依名稱指定單一來源。回應中的 basis、source 與 note 欄位說明由哪個來源提供資料,且同一個回應絕不混用不同來源。夥伴國申報回應與該國自有數字是不同的衡量方式,絕非官方數字。發布機構自己列示、不是 HS 產品的資料行,例如船舶補給品與私人託運貨物,會以發布機構的代碼回傳(章層級為 00,子目層級為 999999),且 product_ 為 null。HS 代碼路由(/)不認得這些代碼,對它們會回傳 404。單一產品路由(/)會回應這些代碼及其資料列,且 product_ 為 null。
貨幣
金額為 currency 所指貨幣的整單位,以十進位字串表示。預設為來源發布時使用的貨幣,例如英國稅務海關總署(HM Revenue & Customs)使用 GBP。currency=USD 會以該月每日匯率的平均值換算各月。各月使用的匯率列在 fx 中,calculated 則標明已換算的欄位。沒有匯率的月份會回傳 404 rate_。若匯率來源無法回應,請求會回傳 503 upstream_。已經是 USD 的回應會原樣回傳。
分頁
limit 設定單頁最多的資料列數,範圍為 1 至 1000,預設為 500。符合條件的資料列較多時,next_ 會帶有下一頁的游標:將它作為 cursor 傳入,其他參數保持不變。來自不同請求的游標會回傳 400 invalid_。total 計算所有頁面中符合條件的資料列。MCP 工具單次結果最多回傳 200 列。
價格
回傳至少一列資料的請求算一次呼叫,每 1,000 次呼叫收費 $2。較長回應的每一頁各算一次呼叫,不論 limit 為何。沒有資料列的回應免費,所有錯誤也免費。
錯誤
這些錯誤使用共用的問題格式,並附有 request_。缺少或無效的金鑰(401)、餘額低於該次呼叫的價格(402)以及每分鐘請求過多(429),是所有路由共有的帳戶錯誤:請見「錯誤與額度」。
| 狀態 | 代碼 | 發生時機 |
|---|---|---|
400 | invalid_query | 缺少參數、參數格式錯誤或超出允許值:例如 level=3、start=2026-13、start 晚於 end、ytd 與 start 一併傳入、hs 長度超過 level,或傳入了 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 | 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 | 目前無法讀取產品檔案。請稍後再試。 |
此頁面對你有幫助嗎?