發起你的第一個 Narwhal API 請求

透過 REST 或 MCP，以同一把金鑰存取經濟數據、FX、棕櫚油價格和國定假日。

本指南先介紹 CPI，再提供四個 API 各自可用的參考文件；這些 API 位於 api.narwhalapi.com。

經濟數據涵蓋範圍

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。涵蓋範圍依操作與國家而異。各項操作均列出其支援的國家。每個資料請求都需要 Bearer 金鑰。

Free 測試版限制： 3,000 次成功請求（每個 UTC 曆月），另設每分鐘 30 次請求。REST 和 MCP 共用相同限額。

設定你的 API 金鑰

將金鑰以 Bearer 權杖形式放入 Authorization 標頭傳送，絕不可放入 URL。建立帳戶以取得免費金鑰，然後閱讀身分驗證指南，再儲存金鑰。

終端

export NARWHAL_API_KEY="nw_live_..."

請求官方 CPI

在路徑中傳入 ISO 三字母國家代碼。省略 period 回傳已接受的最新完整發布版本。

請求

curl --request GET \
  --url https://api.narwhalapi.com/v1/economics/USA/cpi \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

回應範例

{
  "country": "USA",
  "period": "2026-07",
  "value": "333.918",
  "base_period": "1982-84",
  "base_value": "100",
  "released_on": "2026-08-12"
}

Python 和 JavaScript 範例

在應用程式中使用相同的環境變數和端點。這些範例使用內建函式庫。

Python 3

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://api.narwhalapi.com/v1/economics/USA/cpi",
    headers={"Authorization": "Bearer " + os.environ["NARWHAL_API_KEY"]},
)
with urlopen(request, timeout=30) as response:
    data = json.load(response)
print(data)

JavaScript · Node.js 18+

const key = process.env.NARWHAL_API_KEY;
if (!key) throw new Error("Set NARWHAL_API_KEY first");
const response = await fetch(
  "https://api.narwhalapi.com/v1/economics/USA/cpi",
  { headers: { Authorization: "Bearer " + key }, signal: AbortSignal.timeout(30000) }
);
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));
console.log(data);

選擇你的 API

API	從以下項目開始
經濟數據 API	來自官方發布機構的 CPI、通膨、勞動、GDP 與貿易資料。涵蓋範圍依國家與指標而異。
外匯 API	目前匯率、貨幣換算及分頁歷史資料，每筆匯率都附有時間戳記。
國定假日 API	已發布的國定假日資料，涵蓋全國、地區及補假日期。
棕櫚油 API	印尼和馬來西亞的 CPO 與 FFB 價格，保留原始單位和歷史資料。

選擇國家和指標

每個已上線國家都提供九個最新發布操作和九個對應的歷史操作。經濟數據 API 參考列出每條路徑和回應結構。

指標	路徑後綴
CPI	`/cpi`
通膨	`/inflation`
失業率	`/unemployment`
勞動力參與率	`/labour-force-participation`
GDP 與成長率	`/gdp` · `/gdp-growth`
貿易、出口、進口	`/trade` · `/trade/exports` · `/trade/imports`

透過 MCP 連線

透過 MCP 用戶端使用同一把金鑰與相同的結構描述。工具探索會列出你的帳戶在全部四個 API 中可用的操作。請參閱 MCP 指南。

與客戶端無關的欄位映射

{
  "url": "https://api.narwhalapi.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_NARWHAL_API_KEY"
  }
}

透過 MCP 用戶端的安全機密設定替換預留值。純 JSON 本身不會自動展開環境變數。

首次 tools/call

{
  "method": "tools/call",
  "params": {
    "name": "fx_get_rates",
    "arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
  }
}

初始化與 tools/list 不會消耗配額。每次成功的 tools/call 消耗一次請求。

閱讀回應

整合前請讀取每項操作的回應架構。

規則	這意味著什麼
`period`	官方發布版本所回傳的確切月份、季度或年份。
`released_on`	官方發布日期。
十進位字串	數值表示可避免二進位浮點數帶來的意外誤差。
缺失資料	若發布資料不完整或無法使用，則拒絕提供資料；缺失值絕不會變成零。

讀取 Narwhal 如何儲存和更新官方發布版本。

成功回應中的配額標頭

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

按狀態和錯誤代碼處理錯誤

先檢查 HTTP 狀態，接著將 code 用於應用程式邏輯。 detail 用於日誌和偵錯。錯誤和配額指南列出所有公開狀態。

RFC 9457 問題回應

{
  "ok": false,
  "type": "https://narwhalapi.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "The request parameters are not valid for this operation.",
  "code": "invalid_query",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50",
  "instance": "/v1/economics/USA/cpi"
}

需要金鑰相關協助嗎？聯絡 Narwhal API。

查看最新變更：更新日誌。

LLM？閱讀 llms.txt。