貨物貿易歷史資料 API

取得指定國家目前已接受的貨物貿易時間序列。

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

端點與請求

REST 端點

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

請求範例

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/USA/trade/observations?start=2026-06&limit=100" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

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

參數

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

名稱	必填	類型	含義
`country`	是	路徑·ISO alpha-3	一個受支援的大寫國家代碼；請參閱此操作的涵蓋清單。
`start`	否	查詢·YYYY-MM	起始觀測期間（含該期間）。
`end`	否	查詢·YYYY-MM	結束觀測期間（含該期間）。
`limit`	否	查詢·整數，1–1000	最多回傳的觀測值數量。預設為 100。
`cursor`	否	查詢·不透明字串	上一頁回傳的 next_cursor。

回應

回應範例

{
  "observations": [
    {
      "country": "USA",
      "measure": "trade_exports",
      "value": "189000000000",
      "unit": "USD",
      "transformation": "",
      "period": "2026-06"
    }
  ],
  "next_cursor": null,
  "as_of": "2026-08-29T16:00:00Z"
}

欄位	類型	必填	含義
`observations`	陣列	是	按從最早到最近的順序排列已接受的觀測值。缺失的來源數值會被省略，絕不會填補。
`observations[].country`	字串	是	所請求的大寫 ISO 三字母國家代碼。
`observations[].measure`	字串	是	該觀測值所代表的規範指標。
`observations[].period`	字串	是	觀測值所代表的官方月份或季度。
`observations[].value`	十進位數值字串	是	不經過二進位浮點轉換的已接受來源值。
`observations[].unit`	字串	是	該指標的來源單位或貨幣代碼。
`observations[].transformation`	字串	是	指標的轉換方式；若為水準值，則為空字串。
`next_cursor`	字串或 null	否	將此值原樣作為 cursor 傳入，以讀取下一頁。
`as_of`	RFC 3339 時間戳記	否	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 無法安全提供已接受的發布版本。

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

資料時效

此路由回傳 Narwhal 目前已接受的資料序列，時間截至 as_of。這是依目前版本提供的歷史資料，並非重建過去每次發布時的資料版本。

官方來源的資料可能稀疏，且可追溯的歷史長度各不相同。Narwhal 會省略缺失的觀測值，不會以內插法或沿用前值的方式填補。

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

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

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

可用的官方歷史資料依此操作涵蓋的國家而定。首個可用期間依來源而異。

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

回傳所有經濟數據操作。