開放式貿易查詢 API 參考
在一次呼叫中查詢任意申報國、夥伴國與 HS 章,例如某項產品的主要出口國,或兩個國家之間的比較。
概覽
GET /
GET / 在一次呼叫中回傳你所指定的任意申報國、夥伴國與 HS 章的進出口。reporter、partner 與 hs 各自可接受最多 10 項、以逗號分隔的清單。一列資料是一個申報國、月份、流向、夥伴國與章。
適用於跨國家或跨產品的問題:誰出口某一章、一個國家與另一個國家如何貿易,或兩個國家並列比較。reporter、partner 與 hs 至少要指定一個。省略時,reporter 代表 Narwhal 直接收錄的所有國家,即來自其自有機構或 UN Comtrade 者。
每一列都標明自己的 basis、source 與 currency,因為各申報國可能由不同來源提供資料。來自不同來源的資料列絕不加總。區間最多為 12 個月,未帶 start 與 end 時,每個申報國回應其最新月份。未帶 hs 時,資料列為夥伴國總額;帶有 hs 時,則為章的資料列。MCP 工具為 trade_,參數相同。
請求
英國與德國在 2026 年 6 月第 85 章(電機設備)的出口,第一頁(五列):
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=GBR,DEU&hs=85&start=2026-06&end=2026-06&flow=export&limit=5"{
"scope": "goods",
"bases": [
"own"
],
"reporters": [
"DEU"
],
"latest_period": "2026-06",
"note": null,
"fx": null,
"calculated": [],
"total": 396,
"rows": [
{
"reporter": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"currency": "EUR",
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "ABW",
"partner_label": "Aruba",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "108666",
"net_weight_kg": "731"
},
{
"reporter": "DEU",
"basis": "own",
"source": "Eurostat Comext",
"currency": "EUR",
"flow": "export",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "AFG",
"partner_label": "Afghanistan",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "153236",
"net_weight_kg": "2893"
}
],
"next_cursor": "eyJiIjoiZW5kPTIwMjYtMDZ8Zmxvdz1leHBvcnR8aHM9ODV8aW5jbHVkZV9ncm91cHM9RmFsc2V8cmVwb3J0ZXI9R0JSLERFVXxzdGFydD0yMDI2LTA2IiwibyI6NX0"
}此頁顯示五列中的前兩列。total 為 396,因此後面還有更多頁。第 1 頁只有德國的資料列,而 reporters 列出該頁上的申報國,所以即使查詢了兩個國家,它也只顯示 DEU。
參數
| 參數 | 位置 | 類型 | 必填 | 預設值 | 允許值與意義 |
|---|---|---|---|---|---|
reporter | query | 字串 | 否 | 直接收錄的所有國家 | 申報國,ISO 3166-1 alpha-3 代碼,使用大寫,以逗號分隔,最多 10 項,例如 GBR,DEU。不是國家的代碼會回傳 400 並指出該代碼。涵蓋清單以外的國家會回傳 404 country_。沒有任何自有來源收錄的申報國,會由其他國家的申報提供資料,且必須明確指定。 |
partner | query | 字串 | 否 | 所有夥伴國 | 夥伴國,ISO 3166-1 alpha-3 代碼,使用大寫,以逗號分隔,最多 10 項。 |
hs | query | 字串 | 否 | 無 | HS 章,2 位碼,以逗號分隔,最多 10 項,例如 85,87。此時資料列為章的資料列。省略時,資料列為夥伴國總額。開放式查詢僅收錄章。 |
flow | query | 字串 | 否 | 兩個流向 | export 或 import。 |
start | query | 字串,YYYY-MM | 否 | 各申報國的最新月份 | 起始月份,含該月。從 start 到 end 最多 12 個月。 |
end | query | 字串,YYYY-MM | 否 | 各申報國的最新月份 | 結束月份,含該月。僅帶 start 與 end 其中之一時,僅回應該月。 |
basis | query | 字串 | 否 | 各申報國已收錄的最佳來源 | own、third_ 或 partner_。僅由此來源提供資料。對該問題沒有資料列的來源會回傳 404 basis_。 |
currency | query | 字串 | 否 | 各申報國自己的貨幣,標示於每一列 | USD。以各列所屬月份的每日平均匯率換算。 |
include_ | query | 布林值 | 否 | false | true 也會回傳發布機構列示的群組資料列,例如歐盟或東協(ASEAN)。群組資料列絕不計入加總、排名或占比。 |
limit | query | 整數 | 否 | 500 | 1 至 1000。單頁最多的資料列數。 |
cursor | query | 字串 | 否 | 無 | 上一頁的 next_,其他所有參數保持不變。 |
回應
回應包含下列欄位。
| 欄位 | 含義 |
|---|---|
scope | goods。 |
bases | 此回應的資料列所來自的來源,每個皆為 own、third_ 或 partner_。 |
reporters | 此頁有資料列的申報國,已排序。後面的頁面可能列出更多。 |
latest_ | 直接收錄的資料列中最新的月份。沒有時為 null。 |
note | 使用這些數字前請先閱讀。當某一列為夥伴國申報時會設定此欄位,否則為 null。 |
fx | 搭配 currency=USD:各月使用的匯率,附有 period、from_、to_、rate 與 days。否則為 null。 |
calculated | Narwhal 計算出的欄位名稱。 |
total | 所有頁面中符合條件的資料列數。 |
next_ | 下一頁的游標。最後一頁為 null。 |
rows 的每一項是一個申報國、月份、流向、夥伴國與章。
| 欄位 | 含義 |
|---|---|
reporter | 申報國的 ISO 3166-1 alpha-3 代碼。 |
basis | 此列的來源:own、third_ 或 partner_。 |
source | 此列的發布機構。 |
currency | 此列金額的 ISO 4217 代碼。 |
flow | export 或 import。 |
period | 月份,YYYY-MM。 |
period_ | month。 |
period_ | 該列涵蓋的第一天與最後一天,YYYY-MM-DD。 |
partner, partner_ | 與夥伴國路由相同。 |
product_ | 傳入 hs 時為章。夥伴國總額則為 null。 |
value | currency 的整單位,以十進位字串表示。 |
net_ | 淨重(公斤),發布機構有提供時才有。否則為 null。 |
更多範例
僅提供夥伴國總額的申報國會被略過
美國從中國進口第 85 章的資料,同時也指定了加拿大與墨西哥。它們的自有機構僅提供夥伴國總額,因此只有美國有回應:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=USA,CAN,MEX&partner=CHN&hs=85&start=2026-06&end=2026-06&flow=import&limit=5"{
"scope": "goods",
"bases": [
"own"
],
"reporters": [
"USA"
],
"latest_period": "2026-06",
"note": null,
"fx": null,
"calculated": [],
"total": 1,
"rows": [
{
"reporter": "USA",
"basis": "own",
"source": "US Census Bureau",
"currency": "USD",
"flow": "import",
"period": "2026-06",
"period_type": "month",
"period_start": "2026-06-01",
"period_end": "2026-06-30",
"partner": "CHN",
"partner_label": "China",
"partner_kind": "country",
"unallocated_reason": null,
"product_code": "85",
"value": "5834371932",
"net_weight_kg": null
}
],
"next_cursor": null
}僅有夥伴國總額的申報國
當所有指定的申報國都僅提供夥伴國總額,且傳入了 hs 時,呼叫會回傳 404,且免費:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/flows?reporter=CAN&hs=85&start=2026-06&end=2026-06&limit=4"{
"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. See /v1/trade/coverage.",
"code": "basis_not_available",
"request_id": "3dd0d00d-a61f-488c-ab1b-e121c37e4980"
}來源
每個申報國由其收錄的最佳來源提供資料:先是其自有機構,再來是其向 UN Comtrade 提交的申報(僅夥伴國總額),兩者都沒有收錄的申報國則由其他國家的申報提供,標示為 partner_。依章查詢時,UN Comtrade 沒有任何資料。basis 會對所有申報國強制使用同一個來源。自有機構僅提供夥伴國總額的申報國沒有章的資料列:當其他申報國有回應時,它會被略過;若沒有任何申報國能回應,呼叫會回傳 404 basis_。
貨幣
每一列都以其申報國自己的貨幣表示,並標示於該列的 currency。currency=USD 會以各列所屬月份的每日平均匯率換算每一列,並將匯率列在 fx 中。沒有匯率的月份會回傳 404 rate_,匯率來源無法使用時會回傳 503 upstream_。
分頁
limit 設定單頁最多的資料列數,範圍為 1 至 1000,預設為 500。符合條件的資料列較多時,next_ 會帶有下一頁的游標:將它作為 cursor 傳入,其他參數保持不變。來自不同請求的游標會回傳 400 invalid_。total 計算所有頁面中符合條件的資料列。MCP 工具單次結果最多回傳 200 列。
價格
回傳至少一列資料的請求算一次呼叫,每 1,000 次呼叫收費 $2。較長回應的每一頁各算一次呼叫,不論 limit 為何。沒有資料列的回應免費,所有錯誤也免費。
錯誤
這些錯誤使用共用的問題格式,並附有 request_。缺少或無效的金鑰(401)、餘額低於該次呼叫的價格(402)以及每分鐘請求過多(429),是所有路由共有的帳戶錯誤:請見「錯誤與額度」。
| 狀態 | 代碼 | 發生時機 |
|---|---|---|
400 | invalid_query | 未指定 reporter、partner 或 hs(an open query with none is the whole store)、end 早於 start、區間超過 12 個月、清單超過 10 項、申報國不是國家、參數超出允許值,或傳入了 as_ 或 version。另外,當夥伴國申報回應需要超過 30 個申報國、夥伴國與章的組合時也是。 |
400 | invalid_cursor | 此游標不是該請求所回傳的游標,或其後有其他參數已變更。 |
400 | range_too_large | 回應的資料列將超過 200,000 列,或未指定夥伴國的章資料列涵蓋超過 36 個申報國月份。請指定較少的申報國、夥伴國或章,或縮短區間。 |
404 | country_not_covered | 所指定的申報國不在涵蓋清單中(ATA is not in the trade coverage list.)。 |
404 | basis_not_available | basis 指定的來源對該問題沒有資料列,或所指定的每個申報國都僅有夥伴國總額,且傳入了 hs。 |
404 | rate_not_available | 要求了 currency=USD,但某個月份沒有匯率。 |
503 | upstream_unavailable | 匯率來源無法回應。這會影響 currency=USD,以及需要換算的夥伴國申報回應。請稍後再試。 |
503 | trade_data_unavailable | 目前無法讀取產品檔案。請稍後再試。 |
此頁面對你有幫助嗎?