用 Python 调用 API 拉取 Narwhal 数据

你可以用 Python 和 Narwhal，凭一个 API 密钥拉取节假日、发布日期、经济数据、大宗商品现货价格、汇率和预测市场赔率。用 requests 读取 JSON 响应，再用 cron 为脚本安排每日拉取。

你将完成的设置

安装了 requests 的 Python 3 可以让你写出一个调用 Narwhal REST API 的脚本，并读取每个数据领域的响应字段。你将得到一个共用的请求辅助函数、每个领域的示例，以及一条每日 cron 条目。Narwhal 用同一个账户和同一个 API 密钥覆盖其各个数据 API；REST 和 MCP 共用这个密钥。示例使用 https://api.narwhalapi.com 作为基础 URL，并发送 Authorization: Bearer YOUR_KEY。路径用来选择数据领域，每次调用从 JSON 响应中读取对应的字段。

设置你的 API 密钥

  1. 创建免费密钥 在 narwhalapi.com/signup 创建你的免费密钥。每个请求的 Authorization 标头都使用同一个密钥，所以整个脚本都可以用它。
  2. 把密钥保存在 shell 环境中 在你要使用 curl 和 Python 的 shell 中设置 NARWHAL_API_KEY，并把占位符替换成你的密钥。Python 辅助函数在构建 Bearer 标头时读取这个环境变量。
    API 密钥
    export NARWHAL_API_KEY=...
  3. 为 Python 3 安装 requests 为 Python 脚本安装 requests。PyPI 上还有 narwhalapi SDK，可用 pip install narwhalapi 安装。
    安装 requests
    pip install requests

编写 Python 之前先拉取数据

  1. 请求节假日 JSON 使用 curl 和你在 shell 中设置的环境变量。这个请求会向节假日端点发送 Bearer 标头，并在你编写 Python 代码之前打印 JSON。
    节假日请求
    curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/holidays/USA/2026"
  2. 读取节假日行 在 holidays 中查看返回的行。每一行都有 date 和 name；Python 示例先统计行数，然后用这些字段打印第一个节假日。

用代码获取数据

六个请求都使用共用的 get 辅助函数。它把 API 基础 URL 与路径拼接，发送标头，传递查询参数，并在 raise_for_status() 之后读取 JSON。随后各次调用选取每个领域的响应字段，因此 print 语句可以处理节假日行、发布日期、观测值、现货价格、汇率和会议概率。

查询参数留在各自的调用中：发布日期请求包含国家、日期边界和数量上限，而汇率请求包含货币。辅助函数通过 params 发送它们，然后返回解析后的响应。请把辅助函数放在各领域示例之前，这样每个示例都能使用 get、API 和 HEADERS。下面的每个示例都用自己的路径和响应字段复用这个辅助函数。

Python，全部六个领域
import os
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 = get("/v1/calendars/holidays/USA/2026")["holidays"]
releases = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)["releases"]
cpi = get("/v1/economics/USA/cpi/observations", start="2025-09")["observations"]
brent = get("/v1/commodities/spot/BRENT/USD")["price"]
fx = get("/v1/fx/rates/USD", currencies="EUR,IDR")["rates"]
fed = get("/v1/predictions/policy-paths/federal-reserve")["meetings"]

print(len(holidays), holidays[0]["date"], holidays[0]["name"])
print(len(releases), releases[0]["period"], releases[0].get("at"))
print(cpi[-1]["period"], cpi[-1]["value"])
print("Brent", brent)
print({r["currency"]: r["rate"] for r in fx})
print(fed[0]["resolves_at"][:10], fed[0]["p_hold"])

按计划定时运行

可以用一条 cron 条目每天运行一次脚本。使用提供的条目，并把脚本放在 /path/pull.py；它调用 /usr/bin/python3，并把打印输出追加到 pull.log。脚本每天发起六次调用，请求数量很少。

每日 cron 条目
0 7 * * * /usr/bin/python3 /path/pull.py >> pull.log

在任务运行的环境中设置 NARWHAL_API_KEY。在共享机器上，请把密钥放在任务引入的文件中，不要写进 crontab。定时脚本读取的变量与 shell 示例相同，请求也使用同样的 Bearer 标头。

Python 中的节假日

读取 holidays 获取每个节假日的日期和名称。2026 年 10 月 24 日的响应包含 2026 年的 11 个 US 节假日，1 月 1 日的元旦排在第一位。这个示例使用共用的辅助函数，并从第一行打印这两个字段；完整脚本还会打印节假日行的数量。

节假日日期和名称
holidays = get(
    "/v1/calendars/holidays/USA/2026"
)["holidays"]
print(holidays[0]["date"], holidays[0]["name"])

Python 中的发布日期

读取 releases 获取所请求国家和日期范围内的经济发布日期。每个发布都有 at、period、topic 和 status。2026 年 10 月 24 日的响应在 2026 年 11 月的范围内包含 31 个发布。示例打印第一个发布的 period，并像完整脚本一样用 .get() 读取它的 at 字段。

经济数据发布日期
releases = get(
    "/v1/economics/calendar",
    countries="USA",
    start_date="2026-11-01",
    end_date="2026-11-30",
    limit=100,
)["releases"]
print(releases[0]["period"], releases[0].get("at"))

Python 中的经济数据

读取 observations 获取 CPI 的期间和数值，用 start 请求从某个期间开始的观测值。在 2026 年 10 月 24 日的响应中，2026 年 9 月的 CPI 指数为 336.940。每个观测值都有 period 和 value；这个示例从返回的最后一行读取这两个字段。Narwhal 的经济数据还包括通胀、GDP 和收益率。

CPI 观测值
cpi = get(
    "/v1/economics/USA/cpi/observations", start="2025-09"
)["observations"]
print(cpi[-1]["period"], cpi[-1]["value"])

Python 中的大宗商品现货价格

读取 price 获取以 USD 计价的 Brent 现货价格。2026 年 10 月 24 日的响应显示 Brent 为每桶 116.8809 美元。示例把这个字段赋给 brent，并带标签打印出来。大宗商品现货代码包括 XAU、XAG、XPT、XPD、XCU、BRENT 和 WTI 等；这个请求使用 BRENT。

Brent 现货价格
brent = get(
    "/v1/commodities/spot/BRENT/USD"
)["price"]
print("Brent", brent)

Python 中的汇率

读取 rates 获取所请求货币对 USD 的汇率。每一行都有 currency 和 rate，示例把它们转成字典。2026 年 10 月 24 日的响应显示 USD/EUR 为 0.89342，USD/IDR 为 18107.8，均为 2026 年 10 月 23 日的收盘价。这次调用通过 currencies 参数同时请求 EUR 和 IDR。

USD 汇率
fx = get(
    "/v1/fx/rates/USD", currencies="EUR,IDR"
)["rates"]
print({r["currency"]: r["rate"] for r in fx})

Python 中的预测市场赔率

读取 meetings 获取美联储政策利率路径。每次会议都有 resolves_at、p_cut、p_hold 和 p_hike。2026 年 10 月 24 日的响应显示，2026 年 10 月 28 日会议的维持不变概率为 0.9188。这个示例使用与完整脚本相同的字段，打印 resolves_at 的日期部分和第一次会议的 p_hold 值。

美联储会议概率
fed = get(
    "/v1/predictions/policy-paths/federal-reserve"
)["meetings"]
print(fed[0]["resolves_at"][:10], fed[0]["p_hold"])

为什么会得到 401？

Authorization 标头缺失，或者环境变量为空。用 bool(os.environ.get('NARWHAL_API_KEY')) 打印 Python 是否拿到了 NARWHAL_API_KEY 的值。辅助函数用这个变量构建标头，所以要在脚本运行的环境中设置它。预期的标头是 Authorization: Bearer YOUR_KEY，密钥值由环境变量提供。对于定时拉取，请在任务环境中检查变量是否为空。

如何把行列表转成表格？

对你想转成表格的行列表使用 pandas.DataFrame(rows)。节假日调用的列表是 holidays；发布日期的列表是 releases。读取响应行之后如何处理表格，请参阅 pandas 教程。CPI 的 observations、汇率的 rates 和预测的 meetings 字段同样是行列表。在传给 pandas.DataFrame(rows) 之前，先在 Python 中选取响应字段。

发布于。

后续步骤