國內生產毛額（GDP） API

取得某一季以當期價格計算的全國 GDP。

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

端點與請求

REST 端點

GET /v1/economics/{country}/gdp

請求範例

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

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

參數

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

名稱	必填	類型	含義
`country`	是	路徑·ISO alpha-3	一個受支援的大寫國家代碼；請參閱此操作的涵蓋清單。
`period`	否	查詢·YYYY-QN	省略此參數可取得已採納的最新完整發布資料，或傳入一個確切期間。

回應

回應範例

{
  "country": "USA",
  "period": "2026-Q2",
  "value": "31000100000000",
  "currency": "USD",
  "price_basis": "current",
  "seasonal_adjustment": "seasonally_adjusted",
  "annualization": "annualized",
  "released_on": "2026-07-30"
}

欄位	類型	必填	含義
`country`	字串	是	所請求的大寫 ISO 三字母國家代碼。
`period`	字串	是	回傳的官方觀測期間。
`value`	表示正數的十進位數值字串	是	按當期價格計算的 GDP 數值。
`currency`	ISO 4217 字串	是	GDP數值所使用的本國貨幣。
`price_basis`	"current"	是	確認該數值為按當期價格計算的 GDP。
`seasonal_adjustment`	列舉	是	官方序列是否經過季節性調整。
`annualization`	列舉	是	官方數值是否經過年化。
`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 是官方發布日期。

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

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

36 國家

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, QAT, SAU, SGP, SVN, SWE, USA

每季全國 GDP（按當期價格計算）的資料涵蓋下列國家。

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

回傳所有經濟數據操作。