貨物出口 API

取得某個國家在指定期間的貨物出口總額。

economics_get_trade_exports 可透過 REST 或 economics_get_trade_exports MCP 工具呼叫。兩者回傳相同的資料結構，並消耗相同的每月配額。

端點與請求

REST 端點

GET /v1/economics/{country}/trade/exports

請求範例

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/trade/exports?period=2026-06" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

MCP 使用工具 economics_get_trade_exports ，並使用下列對應參數。

REST 發送 product 和 classification 作為獨立的查詢參數傳送。MCP 則將它們巢狀放入同一個 product 對象：

MCP 貿易篩選參數

{
  "country": "USA",
  "period": "2026-06",
  "partner": "CAN",
  "product": {
    "classification": "HS2022",
    "code": "27"
  }
}

參數

此操作接受的期間格式是 YYYY or YYYY-MM。

名稱	必填	類型	含義
`country`	是	路徑·ISO alpha-3	一個受支援的大寫國家代碼；請參閱此操作的涵蓋清單。
`period`	否	查詢·YYYY 或 YYYY-MM	省略此參數可取得已採納的最新完整發布資料，或傳入一個確切期間。
`partner`	否	查詢·ISO alpha-3	API 規格接受此參數，但目前測試版尚未發布依貿易夥伴篩選的總額。
`product`	否	查詢·2、4 或 6 位數字	HS 商品代碼。請與 classification 一併提供。
`classification`	否	查詢·HSYYYY	Harmonized System 的版本。請與 product 一併提供。

回應

回應範例

{
  "country": "USA",
  "period": "2026-06",
  "flow": "export",
  "value": "189000000000",
  "currency": "USD",
  "coverage": "merchandise",
  "partner": null,
  "product": null,
  "released_on": "2026-08-04"
}

欄位	類型	必填	含義
`country`	字串	是	所請求的大寫 ISO 三字母國家代碼。
`period`	字串	是	回傳的官方觀測期間。
`flow`	"export" 或 "import"	是	由路由決定的貨物貿易方向。
`value`	十進位數值字串	是	所選方向對應的貨幣金額。
`currency`	ISO 4217 字串	是	貨幣金額所使用的貨幣。
`coverage`	"merchandise"	是	確認不包含服務貿易。
`partner`	ISO alpha-3 字串或 null	否	若有提供，則為請求中的貿易夥伴篩選條件。若為未經篩選的公開總額，此欄位可為 null 或省略。
`product`	物件或 null	否	若有提供，則為請求中的 HS 分類與商品代碼。若為未經篩選的公開總額，此欄位可為 null 或省略。
`released_on`	日期	是	官方發布日期，而不是 Narwhal 的檢索時間。

錯誤與配額

400 invalid_query — 國家、期間或篩選格式無效。
401 invalid_api_key — Bearer 金鑰缺失或被拒絕。
404 series_not_found — 沒有已核准的觀測值符合請求。
429 rate_limit_exceeded — 已達到網路或帳戶的短時間視窗限制；請依下列標頭指定的等待時間重試： Retry-After。
429 quota_exhausted — 帳戶已達到月度配額。
503 economics_unavailable — Narwhal 無法安全提供已接受的發布版本。

只有成功的資料回應才會消耗配額。請參閱所有錯誤、標頭與重試規則。

資料時效

省略 period 回傳 Narwhal 最新儲存且已接受的發布版本。API 呼叫會讀取 Narwhal 的資料庫，不會即時呼叫官方發布機構。

released_on 是官方發布日期。

讀取來源檢查、驗證、發布版本儲存，以及檢查失敗時的處理方式。

目前公開測試版的涵蓋範圍

35 國家

AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, SAU, SGP, SVN, SWE, USA

未經篩選的全國貨物出口總額資料涵蓋下列國家。API 規格接受貿易夥伴與商品篩選條件，但在篩選後的總額發布前，會回傳 404。

印尼與地區經濟數據路由未公開。每日 FX 資料可透過以下 API 取得：外匯 API。

回傳所有經濟數據操作。