瀏覽全部文件

依夥伴國劃分的貿易 API 參考

讀取一個國家依夥伴國劃分的進出口,每個夥伴國、每個月份與每個流向各一列,並將發布機構自己的總額與各列加總並列。

概覽

GET /v1/trade/{country}/partners

GET /v1/trade/{country}/partners 回傳一個國家依夥伴國劃分的貨物貿易:每個夥伴國、每個月份與每個流向各一列。未帶 start 與 end 時,回應為已收錄的最新月份。

用它來了解一個國家與誰進行貿易、金額多少。同一國家依產品查詢請使用產品路由,單一產品對所有夥伴國請使用單一產品路由。要在一次呼叫中比較多個國家,請使用開放式查詢路由。

每個回應都在 basis 與 source 中標明其來源,並在 totals 中將發布機構自己的總額與各列加總並列。帶有 hs 時,totals 為該產品的總額,且 official_total 為 null。MCP 工具為 trade_get_partners,參數相同。

請求

英國在 2026 年 6 月的三大出口夥伴國,以及實際回應:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/GBR/partners?start=2026-06&end=2026-06&flow=export&top=3"
英國,三大出口夥伴國
{
  "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"
  ],
  "total": 3,
  "rows": [
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "5316654916",
      "net_weight_kg": "76287894",
      "rank": 1,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "export",
      "period": "2026-06",
      "period_type": "month",
      "period_start": "2026-06-01",
      "period_end": "2026-06-30",
      "value": "4735227787",
      "net_weight_kg": "341314142",
      "rank": 2,
      "share": null,
      "change": null,
      "partner": "USA",
      "partner_label": "United States",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

此頁顯示三列中的前兩列。basis 為 own,因此由英國稅務海關總署(HM Revenue & Customs)提供資料,且 official_total 等於 sum_of_rows。因為傳入了 top,所以 rank 有值,並列在 calculated 中。

參數

參數位置類型必填預設值允許值與意義
countrypath字串是無申報國的 ISO 3166-1 alpha-3 代碼,使用大寫,例如 GBR。不是國家的代碼會回傳 400。沒有數字的國家會回傳 404 country_not_covered。
partnerquery字串否所有夥伴國單一夥伴國的 ISO 3166-1 alpha-3 代碼,使用大寫。不是該國夥伴國的代碼會回傳 400 unknown_partner。
flowquery字串否兩個流向export 或 import。
startquery字串,YYYY-MM否已收錄的最新月份起始月份,含該月。帶有 start 而無 end 時,回應會涵蓋至已收錄的最新月份。start 晚於 end 會回傳 400。
endquery字串,YYYY-MM否已收錄的最新月份結束月份,含該月。僅帶 end 時,回應為不晚於該月的最新已收錄月份。
hsquery字串否所有產品僅限此產品的貿易,以 2、4 或 6 位碼表示(85、8517、851713):各夥伴國在其中的占比。其他位數的代碼會回傳 400。泰國以 4 位碼保存,因此對泰國查詢 6 位碼的代碼會回傳 404 basis_not_available。
basisquery字串否已收錄的最佳來源own、third_party 或 partner_reported。依名稱指定單一來源,並略過順序。對該問題沒有資料的來源會回傳 404 basis_not_available。
currencyquery字串否來源自己的貨幣USD。以各月的每日平均匯率換算。
topquery整數否所有資料列1 至 1000。每個月份與流向保留金額最大的 N 個國家資料列,依金額排名,金額相同時以夥伴國代碼決定順序,並為每列加上 rank。群組與未分配的資料列不排名。為計算所得。最多涵蓋 12 個月。不適用於夥伴國申報回應。
sharequery布林值否falsetrue 會為每一列加上 share:其金額除以同月份、同流向各國資料列的加總,以 1 為基準的小數表示,保留 6 位小數。為計算所得。最多涵蓋 12 個月。不適用於夥伴國申報回應。
ytdquery布林值否falsetrue 會將已儲存月份中自 1 月至 end(預設:最新月份)的資料加總,且 period_type 為 year_to_date。請傳入 end,不要傳入 start:帶有 start 的請求會回傳 400。缺少月份會回傳 404 period_not_published。為計算所得。不適用於夥伴國申報回應。
changequery布林值否falsetrue 會為每一列加上 change:去年同月(或年初至今)的資料、兩者的差額,以及雙方的發布狀態。缺少前一年的月份會回傳 404 period_not_published。為計算所得。最多涵蓋 12 個月。不適用於夥伴國申報回應。
include_groupsquery布林值否falsetrue 也會回傳發布機構列示的群組資料列,例如歐盟或東協(ASEAN)。群組資料列絕不計入加總、排名或占比。
limitquery整數否5001 至 1000。單頁最多的資料列數。
cursorquery字串否無上一頁的 next_cursor,其他所有參數保持不變。

回應

回應包含下列欄位。所有資料列都相同的內容,只在此處出現一次。

欄位含義
country回應所屬申報國的 ISO 3166-1 alpha-3 代碼。
basis提供資料的來源:own、third_party(UN Comtrade)或 partner_reported。
source發布機構,例如 HM Revenue & Customs、Eurostat Comext、UN Comtrade 或 Customs reports of other countries。
reporters_included搭配 partner_reported 時:其申報被對調後納入回應的申報國的 count 與 countries。其他來源則為 null。
note使用這些數字前請先閱讀。夥伴國申報回應會設定此欄位,否則為 null。
coveragefull 或 partial。夥伴國申報回應為 partial。
partner_coverage列出所有夥伴國時為 all;發布機構僅列示其主要夥伴國與一列其餘合計時為 top_n。夥伴國申報回應則為 null。
scopegoods。
currency回應中所有金額的 ISO 4217 代碼。
classificationHS,即調和制度(Harmonized System)。
edition當單一版本涵蓋所查詢的每個月份時,為 HS 版本(2007、2012、2017 或 2022)。月份間版本不同時為 null,此時每一列各自標明其版本。
edition_basis發布機構載明版本時為 as_published;由 Narwhal 依年份推算時為 inferred_from_year。
valuation_basis發布機構對貿易的計價方式,例如出口採 FOB、進口採 CIF。未說明時為 not_stated。
trade_system發布機構有說明時為 general 或 special;否則為 not_stated。
partner_basis夥伴國依原產地、發貨地或目的地計算,依發布機構所述。未說明時為 not_stated。
trade_scope數字涵蓋的範圍,例如 all_partners、extra_union_only 或 intra_union_other_method。
latest_periodNarwhal 為此國家與來源收錄的最新月份。
total_basisofficial_total 的依據:customs、balance_of_payments 或 eurostat_concept。發布機構未提供總額時為 null。
totals每個月份與流向各一項:period、flow、official_total(發布機構自己的貨物總額,不存在時為 null)與 sum_of_rows(該月份與流向中,除群組資料列外所有夥伴國資料列的加總,為計算所得)。未帶 hs 時,它包含該月的整體貨物總額,即使 partner 限制了資料列也是如此。帶有 hs 時(以及在單一產品路由上),它改為包含該產品的總額:sum_of_rows 是回應中所有頁面資料列的加總(若有指定 partner,則為該夥伴國的;top 與分頁不會截斷它),而 official_total 為 null,因為發布機構沒有列示單一產品的總額。
fx搭配 currency=USD,以及以多種貨幣呈現的夥伴國申報回應時:各月使用的匯率,附有 period、from_currency、to_currency、rate,以及平均值所含的 days。其他情況為 null。
calculatedNarwhal 計算出的欄位名稱,例如 sum_of_rows、rank、share、value 或 official_total。
total所有頁面中符合條件的資料列數。
next_cursor下一頁的游標。最後一頁為 null。

rows 的每一項是一個月份與流向中的一個夥伴國。

欄位含義
flowexport 或 import。
period月份,YYYY-MM。年初至今時為其最後一個月。
period_typemonth 或 year_to_date。
period_start, period_end該列涵蓋的第一天與最後一天,YYYY-MM-DD。
valuecurrency 的整單位,以十進位字串表示。
net_weight_kg淨重(公斤),以十進位字串表示,發布機構有提供時才有。否則為 null。
rank搭配 top:該列的排名,最大者為 1。否則為 null。
share搭配 share:該列占總額的比例,6 位小數。否則為 null。
change搭配 change:一個物件,包含 previous_period、previous_value、absolute(金額減去前期金額)、percent(百分比,4 位小數,前期金額為 0 時為 null)、release_status 與 previous_release_status(preliminary、revised、final,發布機構未說明時為 null)。去年同期的資料列不存在,或未要求 change 時為 null。
partner夥伴國的 ISO 3166-1 alpha-3 代碼、群組代碼(例如 EUU),或在沒有國家的資料行中為空。
partner_label發布機構自己對該夥伴國的稱呼。
partner_kindcountry、group 或 unallocated。
unallocated_reason未分配的資料列:not_specified、confidential、stores_bunkers、free_zone、other 或 rest。否則為 null。

更多範例

單一夥伴國的兩個流向

德國與中國,2026 年 1 月至 6 月,兩個流向:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/DEU/partners?partner=CHN&start=2026-01&end=2026-06"
德國與中國
{
  "country": "DEU",
  "basis": "own",
  "source": "Eurostat Comext",
  "reporters_included": null,
  "note": null,
  "coverage": "full",
  "partner_coverage": "all",
  "scope": "goods",
  "currency": "EUR",
  "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": "eurostat_concept",
  "totals": [
    {
      "period": "2026-01",
      "flow": "export",
      "official_total": "121792305000",
      "sum_of_rows": "121792305000"
    },
    {
      "period": "2026-01",
      "flow": "import",
      "official_total": "106754947046",
      "sum_of_rows": "106754947046"
    }
  ],
  "fx": null,
  "calculated": [
    "sum_of_rows"
  ],
  "total": 12,
  "rows": [
    {
      "flow": "export",
      "period": "2026-01",
      "period_type": "month",
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "value": "5559611667",
      "net_weight_kg": "355538457",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    },
    {
      "flow": "import",
      "period": "2026-01",
      "period_type": "month",
      "period_start": "2026-01-01",
      "period_end": "2026-01-31",
      "value": "8853410701",
      "net_weight_kg": "1020758294",
      "rank": null,
      "share": null,
      "change": null,
      "partner": "CHN",
      "partner_label": "China",
      "partner_kind": "country",
      "unallocated_reason": null
    }
  ],
  "next_cursor": null
}

此頁顯示 12 列中的前兩列,以及 12 個 totals 項目中的前兩項。德國的資料來自 Eurostat Comext,以歐元計。

該國自有機構未提供的產品

加拿大的自有機構僅提供夥伴國總額。查詢單一產品會回傳 404,且免費:

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/trade/CAN/partners?hs=8517&start=2026-06&end=2026-06&limit=3"
加拿大,產品 8517
{
  "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 answers are held at chapter level only (hs of 2 digits). See /v1/trade/coverage.",
  "code": "basis_not_available",
  "request_id": "ebc75b49-165e-44b4-841d-8f80dc308295"
}

來源

每個請求由一個來源提供資料,依此順序採用第一個有資料列的來源:該國自有的海關或統計機構(basis 為 own)、該國向 UN Comtrade 提交的申報(third_party,僅夥伴國總額),然後是其他國家對該國的申報,並將流向對調(partner_reported)。其他國家的申報,只有在至少 200 個申報國有關於該國的資料列時,才會排在 UN Comtrade 之前,這超過 Narwhal 所收錄的數量,因此它們排在最後。依產品查詢時,UN Comtrade 沒有任何資料,所以順序是 own,然後是 partner_reported,且 partner_reported 僅達章(2 位碼)。basis 可依名稱指定單一來源。回應中的 basis、source 與 note 欄位說明由哪個來源提供資料,且同一個回應絕不混用不同來源。夥伴國申報回應與該國自有數字是不同的衡量方式,絕非官方數字。某個來源的夥伴國清單可能很短:當 partner_coverage 為 top_n 時,發布機構僅列出其主要夥伴國與一列其餘合計,各列加總後仍等於總額。

貨幣

金額為 currency 所指貨幣的整單位,以十進位字串表示。預設為來源發布時使用的貨幣,例如英國稅務海關總署(HM Revenue & Customs)使用 GBP。currency=USD 會以該月每日匯率的平均值換算各月。各月使用的匯率列在 fx 中,calculated 則標明已換算的欄位。沒有匯率的月份會回傳 404 rate_not_available。若匯率來源無法回應,請求會回傳 503 upstream_unavailable。已經是 USD 的回應會原樣回傳。

分頁

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

價格

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

錯誤

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

狀態代碼發生時機
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 個月的區間。
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 參考 · 貿易國家

此頁面對你有幫助嗎?