用 Python pandas API 在 Jupyter 中使用 Narwhal API

你将完成的设置

Jupyter 是这个 pandas 工作流所用的笔记本。最终你会得到一个请求辅助函数、装有返回记录的 DataFrame，以及数值形式的 Brent 现货价格。Narwhal 用一个账户、一个 API 密钥覆盖全部数据 API，REST 与 MCP 共用该密钥。笔记本通过 REST 向 https://api.narwhalapi.com 发起请求，密钥放在 Authorization: Bearer YOUR_KEY 请求头中。经济数据 API 包括 CPI、通胀、GDP 和收益率；这个笔记本用 CPI 观测值计算环比。

设置你的 API 密钥

1. 创建免费密钥 在 Narwhal 注册页获取免费密钥，并把它用于笔记本中各个数据领域的请求。
2. 安装笔记本所需的包 打开笔记本之前，先安装 pandas、requests 和 Jupyter。代码用 requests 发起 HTTP 调用，用 pandas 处理返回的记录。
   安装包

   pip install pandas requests jupyter

3. 设置密钥并启动 Jupyter 把 YOUR_KEY 换成你的密钥，并在启动 Jupyter Lab 之前导出 NARWHAL_API_KEY。不要把密钥写进会保存的笔记本单元格；Python 代码从环境变量读取。单元格里的 os.environ 查找在构建 Bearer 请求头时使用的正是这个变量名。
   带着密钥启动 Jupyter

   export NARWHAL_API_KEY=YOUR_KEY
   jupyter lab

用代码获取数据

把这段 Python 代码放进你的笔记本。pd.read_json(url) 无法发送认证请求头，所以由 get 辅助函数用 requests 发出请求并返回 JSON。每个 DataFrame 使用对应领域的响应字段。CPI 计算用返回的水平值求环比，预测日期则用 pd.to_datetime 转换。该辅助函数通过 params 传递查询参数，每次调用都发送 HEADERS，并设置 timeout=10。读取 JSON 响应之前，它会先调用 raise_for_status()。请让这个辅助函数与各领域的调用放在一起，使每个请求都采用相同的认证处理。

import os
import pandas as pd
import requests

API = "https://api.narwhalapi.com"
HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}


def get(path, **params):
    r = requests.get(API + path, params=params, headers=HEADERS, timeout=10)
    r.raise_for_status()
    return r.json()


holidays = pd.DataFrame(get("/v1/calendars/holidays/USA/2026")["holidays"])
releases = pd.DataFrame(
    get(
        "/v1/economics/calendar",
        countries="USA",
        start_date="2026-11-01",
        end_date="2026-11-30",
        limit=100,
    )["releases"]
)
cpi = pd.DataFrame(
    get("/v1/economics/USA/cpi/observations", start="2025-09")["observations"]
)
fx = pd.DataFrame(get("/v1/fx/rates/USD", currencies="EUR,IDR")["rates"])
fed = pd.DataFrame(get("/v1/predictions/policy-paths/federal-reserve")["meetings"])
brent = float(get("/v1/commodities/spot/BRENT/USD")["price"])

cpi["value"] = cpi["value"].astype(float)
cpi["mom_pct"] = cpi["value"].pct_change() * 100
fed["resolves_at"] = pd.to_datetime(fed["resolves_at"]).dt.date

print(holidays[["date", "name"]].head(3))
print(cpi[["period", "value", "mom_pct"]].tail(3))
print(fx)
print(fed[["resolves_at", "p_cut", "p_hold", "p_hike"]].head(2))
print("Brent", brent)

截至 2026 年 10 月 24 日，最近三行 CPI 数据为：2026 年 7 月 333.918，环比 -0.01%；2026 年 8 月 334.980，环比 0.32%；2026 年 9 月 336.940，环比 0.59%。mom_pct 列由 CPI 水平值通过 pct_change() * 100 计算得出。

按计划定时运行

用 jupyter nbconvert 把笔记本转换成脚本，然后通过 cron 运行该脚本。定时运行的脚本同样要把密钥放在 NARWHAL_API_KEY 中：其 HEADERS 赋值读取的环境变量与笔记本相同。转换命令使用 pull.ipynb 作为笔记本文件名。

jupyter nbconvert --to script pull.ipynb

也可以在定时作业中调用同样的函数。该作业使用笔记本里的请求辅助函数和各领域调用，并通过 HEADERS 提供 Bearer 请求头。有关安排拉取，请见安排每日数据拉取。

在 pandas 中使用节假日

从 holidays 响应字段读取 2026 年美国节假日。每个节假日都有 date 和 name，因此这两列能让你在笔记本里并排看到节假日日期和名称。此示例使用与完整单元格相同的带认证 get 辅助函数，并选取这些字段来显示。使用各领域示例之前，请先定义好该辅助函数。

data = get("/v1/calendars/holidays/USA/2026")
holidays = pd.DataFrame(data["holidays"])
print(holidays[["date", "name"]].head(3))

在 pandas 中使用发布日期

用经济日历拉取 2026 年 11 月 1 日至 2026 年 11 月 30 日的美国发布数据，并设置 limit=100。响应字段是 releases，其记录包含 at、period、topic 和 status，可以放在 DataFrame 中一起显示。发布日期用这个调用；按期间查看 CPI 水平值，则用经济数据示例中的观测值调用。

data = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)
releases = pd.DataFrame(data["releases"])
print(releases[["at", "period", "topic", "status"]])

在 pandas 中使用经济数据

使用 start=2025-09 请求 USA 的 CPI 观测值，并将 observations 读入 DataFrame。每条记录都有 period 和 value。计算环比变化之前，请先转换 value 列。

data = get("/v1/economics/USA/cpi/observations", start="2025-09")
cpi = pd.DataFrame(data["observations"])
cpi["value"] = cpi["value"].astype(float)
cpi["mom_pct"] = cpi["value"].pct_change() * 100
print(cpi[["period", "value", "mom_pct"]].tail(3))

在 pandas 中使用大宗商品现货价格

Brent 调用读取 price 字段并转成 float。它使用 BRENT 作为现货代码，请求路径里用 USD。现货代码例如有 XAU、XAG、XPT、XPD、XCU、BRENT 和 WTI。在这个示例中，保持 Brent 的路径不变，并在笔记本里使用 float 返回的数值。

data = get("/v1/commodities/spot/BRENT/USD")
brent = float(data["price"])
print("Brent", brent)

在 pandas 中使用汇率

这个示例中的汇率，用 USD 汇率路径加上 currencies=EUR,IDR 来请求。把 rates 字段读入 DataFrame，每条返回的记录都有 currency 和 rate。选取这两列，就能让货币紧挨着它的汇率。该请求与 CPI 和节假日调用使用相同的密钥和请求头。

data = get("/v1/fx/rates/USD", currencies="EUR,IDR")
fx = pd.DataFrame(data["rates"])
print(fx[["currency", "rate"]])

在 pandas 中使用预测市场赔率

从 meetings 字段读取美联储政策路径。每场会议都有 resolves_at、p_cut、p_hold 和 p_hike。用与完整单元格相同的 pandas 表达式把 resolves_at 转成日期，再与概率字段并排显示。这样，会议的决议日期以及降息、按兵不动和加息字段就会一起出现在笔记本输出中。

data = get("/v1/predictions/policy-paths/federal-reserve")
fed = pd.DataFrame(data["meetings"])
fed["resolves_at"] = pd.to_datetime(fed["resolves_at"]).dt.date
print(fed[["resolves_at", "p_cut", "p_hold", "p_hike"]].head(2))

为什么我的数字是文本?

API 为保持精度，会把小数以字符串返回。需要数值计算时，对 DataFrame 的列使用 astype(float)，例如 cpi["value"].astype(float)。对于单个 Brent 价格，示例对返回的 price 字段使用 float。只对需要做算术运算的值进行转换。值变成数字后，响应字段名保持不变。

如何得到同比?

调用 /v1/economics/USA/inflation 获取总体通胀率。它会返回 year_over_year 和 month_over_month。用 CPI 水平值计算同比，需要被比较月份 12 个月前的水平值，因此请至少请求 13 个月的水平值。