瀏覽全部文件

開放式貿易查詢 API 參考

在一次呼叫中查詢任意申報國、夥伴國與 HS 章,例如某項產品的主要出口國,或兩個國家之間的比較。

概覽

GET /v1/trade/flows

GET /v1/trade/flows 在一次呼叫中回傳你所指定的任意申報國、夥伴國與 HS 章的進出口。reporter、partner 與 hs 各自可接受最多 10 項、以逗號分隔的清單。一列資料是一個申報國、月份、流向、夥伴國與章。

適用於跨國家或跨產品的問題:誰出口某一章、一個國家與另一個國家如何貿易,或兩個國家並列比較。reporter、partner 與 hs 至少要指定一個。省略時,reporter 代表 Narwhal 直接收錄的所有國家,即來自其自有機構或 UN Comtrade 者。

每一列都標明自己的 basis、source 與 currency,因為各申報國可能由不同來源提供資料。來自不同來源的資料列絕不加總。區間最多為 12 個月,未帶 start 與 end 時,每個申報國回應其最新月份。未帶 hs 時,資料列為夥伴國總額;帶有 hs 時,則為章的資料列。MCP 工具為 trade_get_flows,參數相同。

請求

英國與德國在 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"
第 85 章出口,英國與德國
{
  "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。

參數

參數位置類型必填預設值允許值與意義
reporterquery字串否直接收錄的所有國家申報國,ISO 3166-1 alpha-3 代碼,使用大寫,以逗號分隔,最多 10 項,例如 GBR,DEU。不是國家的代碼會回傳 400 並指出該代碼。涵蓋清單以外的國家會回傳 404 country_not_covered。沒有任何自有來源收錄的申報國,會由其他國家的申報提供資料,且必須明確指定。
partnerquery字串否所有夥伴國夥伴國,ISO 3166-1 alpha-3 代碼,使用大寫,以逗號分隔,最多 10 項。
hsquery字串否無HS 章,2 位碼,以逗號分隔,最多 10 項,例如 85,87。此時資料列為章的資料列。省略時,資料列為夥伴國總額。開放式查詢僅收錄章。
flowquery字串否兩個流向export 或 import。
startquery字串,YYYY-MM否各申報國的最新月份起始月份,含該月。從 start 到 end 最多 12 個月。
endquery字串,YYYY-MM否各申報國的最新月份結束月份,含該月。僅帶 start 與 end 其中之一時,僅回應該月。
basisquery字串否各申報國已收錄的最佳來源own、third_party 或 partner_reported。僅由此來源提供資料。對該問題沒有資料列的來源會回傳 404 basis_not_available。
currencyquery字串否各申報國自己的貨幣,標示於每一列USD。以各列所屬月份的每日平均匯率換算。
include_groupsquery布林值否falsetrue 也會回傳發布機構列示的群組資料列,例如歐盟或東協(ASEAN)。群組資料列絕不計入加總、排名或占比。
limitquery整數否5001 至 1000。單頁最多的資料列數。
cursorquery字串否無上一頁的 next_cursor,其他所有參數保持不變。

回應

回應包含下列欄位。

欄位含義
scopegoods。
bases此回應的資料列所來自的來源,每個皆為 own、third_party 或 partner_reported。
reporters此頁有資料列的申報國,已排序。後面的頁面可能列出更多。
latest_period直接收錄的資料列中最新的月份。沒有時為 null。
note使用這些數字前請先閱讀。當某一列為夥伴國申報時會設定此欄位,否則為 null。
fx搭配 currency=USD:各月使用的匯率,附有 period、from_currency、to_currency、rate 與 days。否則為 null。
calculatedNarwhal 計算出的欄位名稱。
total所有頁面中符合條件的資料列數。
next_cursor下一頁的游標。最後一頁為 null。

rows 的每一項是一個申報國、月份、流向、夥伴國與章。

欄位含義
reporter申報國的 ISO 3166-1 alpha-3 代碼。
basis此列的來源:own、third_party 或 partner_reported。
source此列的發布機構。
currency此列金額的 ISO 4217 代碼。
flowexport 或 import。
period月份,YYYY-MM。
period_typemonth。
period_start, period_end該列涵蓋的第一天與最後一天,YYYY-MM-DD。
partner, partner_label, partner_kind, unallocated_reason與夥伴國路由相同。
product_code傳入 hs 時為章。夥伴國總額則為 null。
valuecurrency 的整單位,以十進位字串表示。
net_weight_kg淨重(公斤),發布機構有提供時才有。否則為 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"
第 85 章自中國進口
{
  "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"
加拿大,第 85 章
{
  "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_reported。依章查詢時,UN Comtrade 沒有任何資料。basis 會對所有申報國強制使用同一個來源。自有機構僅提供夥伴國總額的申報國沒有章的資料列:當其他申報國有回應時,它會被略過;若沒有任何申報國能回應,呼叫會回傳 404 basis_not_available。

貨幣

每一列都以其申報國自己的貨幣表示,並標示於該列的 currency。currency=USD 會以各列所屬月份的每日平均匯率換算每一列,並將匯率列在 fx 中。沒有匯率的月份會回傳 404 rate_not_available,匯率來源無法使用時會回傳 503 upstream_unavailable。

分頁

limit 設定單頁最多的資料列數,範圍為 1 至 1000,預設為 500。符合條件的資料列較多時,next_cursor 會帶有下一頁的游標:將它作為 cursor 傳入,其他參數保持不變。來自不同請求的游標會回傳 400 invalid_cursor。total 計算所有頁面中符合條件的資料列。MCP 工具單次結果最多回傳 200 列。

價格

回傳至少一列資料的請求算一次呼叫,每 1,000 次呼叫收費 $2。較長回應的每一頁各算一次呼叫,不論 limit 為何。沒有資料列的回應免費,所有錯誤也免費。

錯誤

這些錯誤使用共用的問題格式,並附有 request_id。缺少或無效的金鑰(401)、餘額低於該次呼叫的價格(402)以及每分鐘請求過多(429),是所有路由共有的帳戶錯誤:請見「錯誤與額度」。

狀態代碼發生時機
400invalid_query未指定 reporter、partner 或 hs(an open query with none is the whole store)、end 早於 start、區間超過 12 個月、清單超過 10 項、申報國不是國家、參數超出允許值,或傳入了 as_of 或 version。另外,當夥伴國申報回應需要超過 30 個申報國、夥伴國與章的組合時也是。
400invalid_cursor此游標不是該請求所回傳的游標,或其後有其他參數已變更。
400range_too_large回應的資料列將超過 200,000 列,或未指定夥伴國的章資料列涵蓋超過 36 個申報國月份。請指定較少的申報國、夥伴國或章,或縮短區間。
404country_not_covered所指定的申報國不在涵蓋清單中(ATA is not in the trade coverage list.)。
404basis_not_availablebasis 指定的來源對該問題沒有資料列,或所指定的每個申報國都僅有夥伴國總額,且傳入了 hs。
404rate_not_available要求了 currency=USD,但某個月份沒有匯率。
503upstream_unavailable匯率來源無法回應。這會影響 currency=USD,以及需要換算的夥伴國申報回應。請稍後再試。
503trade_data_unavailable目前無法讀取產品檔案。請稍後再試。

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

此頁面對你有幫助嗎?