商品進口 API

獲取一個國家某個期間的商品進口總額。

economics_get_trade_imports 可通過 REST 和 economics_get_trade_imports MCP 工具。兩者返回相同的數據結構，並消耗相同的月度配額。

端点與請求

REST 端點

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

請求範例

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

MCP 使用工具 economics_get_trade_imports 使用下面對應的參數。

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	支援的一個大寫國家代碼：AUS、CAN、DEU、FRA、GBR、JPN、MYS、NLD、SGP 和 USA。
`period`	否	查詢·YYYY 或 YYYY-MM	省略此參數可獲取最新已接受的完整發布，或傳入一個精確期間。
`partner`	否	查詢·ISO alpha-3	根據合約已接受，但當前測試版不會發布篩選後的合作夥伴總數。
`product`	否	查詢·2、4 或 6 位數字	HS 商品代碼。請將其與分類一並提供。
`classification`	否	查詢·HSYYYY	《協調制度》的版本。請與product一同提供。

回應

回應範例

{
  "country": "USA",
  "period": "2026-06",
  "flow": "import",
  "value": "275000000000",
  "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 是官方發布日期。

讀取源檢查、驗證、已儲存發布版本和失敗檢查的工作方式.

當前公開測試覆蓋範圍

AUS、CAN、DEU、FRA、GBR、JPN、MYS、NLD、SGP和USA的未篩選全國商品進口總額已公開。契約接受夥伴和產品篩選條件，但在篩選總額發布前會返回404。

印度尼西亞、區域路由和 Commodities 尚未公開。FX 可通過單獨的 FX API.

返回所有經濟數據操作.