发起你的第一个 Narwhal API 请求

通过 REST 或 MCP，使用同一个密钥访问经济数据、外汇、棕榈油价格和节假日。

本指南从 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.