FXMacroData

FXMacroData Python SDK 🐍📊

FXMacroData Python SDK 提供了简单高效的接口，可从 FXMacroData 获取宏观经济指标、外汇价格、发布日期日历、COT 持仓数据和大宗商品价格。

通过同步和异步客户端，可将数据导入研究笔记本、回测和应用程序。

订阅 FXMacroData，即可获取非 USD 数据、完整可用历史数据、外汇、大宗商品和持仓数据。在关联订阅之前，可使用公开的 USD 工作流评估集成效果。

---

🌟 功能

• 获取：
  • 宏观经济指标 — 政策利率、通胀、GDP、失业率、债券收益率等：涵盖 656 个端点上的 97 种不同指标
  • 外汇即期汇率，可选技术指标（SMA、RSI、MACD、布林带）
  • 发布日期日历 — 即将发布的经济数据日期
  • 数据目录 — 按货币查看可用指标
  • COT 数据 — CFTC 交易者持仓报告数据
  • 大宗商品价格 — 黄金、白银、铂金
• 使用涵盖最近 90 天的公开 USD 宏观数据进行评估；关联 FXMacroData 订阅即可获取完整可用历史数据。
• 通过 get_fx_price 获取外汇即期汇率历史数据。
• 受保护的数据集需要授权的 FXMacroData 订阅密钥，包括非 USD 指标、外汇即期汇率历史数据、COT 和大宗商品数据。
• 全面支持：
  • 同步客户端
  • 异步客户端
• 轻量级：仅依赖 requests 和 aiohttp。

---

📦 安装

从 PyPI 安装：

pip install fxmacrodata

或从 GitHub 安装最新版本：

pip install git+https://github.com/fxmacrodata/fxmacrodata.git

---

🔧 使用

同步

from fxmacrodata import Client

client = Client(api_key="YOUR_API_KEY")

# Fetch macroeconomic indicators
data = client.get_indicator(
    "aud", "policy_rate",
    start_date="2023-01-01",
    end_date="2023-11-01"
)
print(data)

# Forex price endpoint
fx = client.get_fx_price("usd", "gbp", start_date="2025-01-01")
print(fx)

# Forex with technical indicators
fx = client.get_fx_price("eur", "usd", indicators="sma_20,rsi_14,macd")
print(fx)

# Release calendar
calendar = client.get_calendar("usd")
print(calendar)

# Data catalogue — discover available indicators
catalogue = client.get_data_catalogue("usd")
print(catalogue)

# COT positioning data
cot = client.get_cot("eur", start_date="2025-01-01")
print(cot)

# Commodity prices
gold = client.get_commodities("gold", start_date="2026-01-01")
print(gold)

---

异步

import asyncio
from fxmacrodata import AsyncClient

async def main():
    async with AsyncClient(api_key="YOUR_API_KEY") as client:
        # Fetch macroeconomic indicators
        data = await client.get_indicator("eur", "inflation")
        print(data)

        # Forex price endpoint
        fx = await client.get_fx_price("usd", "jpy")
        print(fx)

        # Release calendar
        calendar = await client.get_calendar("usd")
        print(calendar)

        # Data catalogue
        catalogue = await client.get_data_catalogue("usd")
        print(catalogue)

        # COT positioning
        cot = await client.get_cot("jpy")
        print(cot)

        # Commodity prices
        gold = await client.get_commodities("gold")
        print(gold)

asyncio.run(main())

超时和错误

每个请求默认超时时间为 30 秒。可针对每个客户端修改：

Client(api_key="YOUR_API_KEY", timeout=60)            # seconds
Client(api_key="YOUR_API_KEY", timeout=(3.05, 120))   # (connect, read)
AsyncClient(api_key="YOUR_API_KEY", timeout=60)       # total seconds

所有错误均为 FXMacroDataError 或其子类：

异常	触发条件
FXMacroDataAPIError	API 返回非 200 状态码（会设置 .status_code）。
FXMacroDataResponseError	API 返回 200，但响应正文是错误消息或不是 JSON 对象。
FXMacroDataTimeoutError	请求超时。
FXMacroDataTransportError	连接失败（DNS、TLS、网络）。
FXMacroDataRedirectError	重定向会将 API 密钥发送到不同来源，因此被拒绝。

错误消息中绝不会包含 API 密钥，且密钥仅会通过 HTTPS 发送到你配置的来源：如果重定向到其他主机或普通 HTTP， 则会被拒绝，而不会附带密钥继续跟随重定向。

---

OpenBB 集成

FXMacroData 支持通过此软件包实现所有实用的 OpenBB 集成方式：

• OpenBB Python：可安装的提供方／路由扩展，适用于 obb.fxmacrodata.*。
• OpenBB REST API：通过 openbb-api 提供 /api/v1/fxmacrodata/* 路由。
• OpenBB Workspace，自动生成：由 openbb-api 根据内联元数据生成的小组件。
• OpenBB Workspace，自定义：提供 widgets.json、apps.json 和数据端点的独立后端。
• OpenBB MCP：通过 openbb-mcp 提供的工具。
• OpenBB CLI：运行 openbb-build 后可用的命令。

OpenBB 软件包需要 Python 3.10+。安装 OpenBB Python 扩展：

pip install "fxmacrodata[openbb]"
openbb-build

然后通过 OpenBB Python 接口使用 FXMacroData：

from openbb import obb

obb.user.credentials.fxmacrodata_api_key = "YOUR_API_KEY"

catalogue = obb.fxmacrodata.data_catalogue(
    currency="USD",
    provider="fxmacrodata",
).to_df()

inflation = obb.fxmacrodata.macro_indicators(
    currency="USD",
    indicator="inflation",
    start_date="2020-01-01",
    provider="fxmacrodata",
).to_df()

eurusd = obb.fxmacrodata.fx_historical(
    base="EUR",
    quote="USD",
    start_date="2024-01-01",
    provider="fxmacrodata",
).to_df()

运行 OpenBB REST API 和自动生成的 Workspace 后端：

pip install "fxmacrodata[openbb-api]"
openbb-build
fxmacrodata-openbb-api --host 127.0.0.1 --port 6900

Workspace 可连接到 http://127.0.0.1:6900。自动生成的 /widgets.json 使用 FXMacroData 的内联 OpenBB 小组件元数据。

运行 OpenBB Workspace 自定义后端：

pip install "fxmacrodata[workspace]"
fxmacrodata-openbb-backend

默认后端 URL：

http://127.0.0.1:7779

Workspace 提供 /widgets.json、/apps.json、/catalogue、 /release_calendar、/macro_indicator、/forex、/cot 和 /commodity。 此后端默认禁用 Swagger/OpenAPI 文档。仅用于本地调试时，请在启动前 设置 FXMACRODATA_OPENBB_ENABLE_DOCS=1。

运行 OpenBB MCP：

pip install "fxmacrodata[mcp]"
openbb-build
fxmacrodata-openbb-mcp --default-categories fxmacrodata --host 127.0.0.1 --port 8001

运行 OpenBB CLI：

pip install "fxmacrodata[openbb-cli]"
openbb-build
openbb

完整的集成矩阵以及单独的上游 OpenBB 仓库贡献方式，请参阅 docs/openbb-integration.md。

---

📘 API 概览

get_indicator(currency, indicator, start_date=None, end_date=None)

获取宏观经济指标时间序列数据。

• currency："usd"、"aud"、"eur"、"gbp"、"cad"、"nok"、"nzd"、"jpy"、"brl"、"cny"、"dkk"、"pln"、"sek"、"sgd" 等。
• indicator："policy_rate"、"inflation"、"gdp"、"unemployment"、"trade_balance"、"current_account_balance"、"gov_bond_10y" 等。
• 非 USD 货币需要 API 密钥。

get_fx_price(base, quote, start_date=None, end_date=None, indicators=None)

获取两种货币之间的每日外汇即期汇率。

• indicators：可选的、以逗号分隔的技术指标——"sma_20"、"sma_50"、"sma_200"、"rsi_14"、"macd"、"ema_12"、"ema_26"、"bollinger_bands" 或 "all"。
• 需要 API 密钥。

get_calendar(currency, indicator=None)

获取某种货币即将发布的经济数据日期。

• indicator：可选，筛选指定的指标 slug。
• 返回 announcement_datetime（Unix 时间戳）和 release（指标 slug）。

get_data_catalogue(currency, include_capabilities=False, include_coverage=False, indicator=None)

发现指定货币可用的宏观经济指标。

• 返回一个以指标 slug 为键的字典，包含 name、unit、frequency 和 has_official_forecast。
• 非 USD 货币需要 API 密钥。

get_cot(currency, start_date=None, end_date=None)

获取 CFTC 交易者持仓报告（COT）数据。

• 支持的货币：AUD、CAD、CHF、EUR、GBP、JPY、NZD、USD。
• 非 USD 货币需要 API 密钥。

get_commodities(indicator, start_date=None, end_date=None)

获取大宗商品价格时间序列。

• indicator："gold"、"silver" 或 "platinum"。
• 需要 API 密钥。

---

💹 支持的货币和指标

支持 18 种货币： AUD、BRL、CAD、CHF、CNH、CNY、DKK、EUR、GBP、ILS、JPY、NGN、NOK、NZD、PEN、SEK、THB、USD。

下表展示了四种主要货币的部分指标覆盖情况。使用 get_data_catalogue() 可发现任意货币的完整列表。

类别	指标	USD	EUR	AUD	GBP
经济	GDP 增长	✓	✓	✓	✓
	通胀率	✓	✓	✓	✓
	贸易差额	✓	✓	✓	✓
	经常账户余额	✓	✓	✓	✓
	零售销售	✓	✓	✓	✓
	工业生产	✓	—	—	—
劳动力市场	失业率	✓	✓	✓	✓
	就业人数	✓	✓	✓	✓
	全职就业人数	✓	✓	✓	—
	兼职就业人数	✓	✓	✓	✓
	劳动参与率	✓	✓	✓	✓
	非农就业人数	✓	—	—	—
货币政策	政策利率	✓	✓	✓	✓
	无风险利率	✓	✓	✓	✓
	央行资产	✓	—	✓	—
政府债券收益率	2 年期政府债券	✓	✓	✓	✓
	5 年期政府债券	✓	✓	✓	✓
	10 年期政府债券	✓	✓	✓	✓
	通胀挂钩债券	✓	✓	✓	✓

---

📄 许可证

MIT 许可证 © FXMacroData

---

🌐 链接

• 网站：https://fxmacrodata.com/?utm_source=github&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=readme
• API 文档：https://fxmacrodata.com/docs?utm_source=github&utm_medium=referral&utm_campaign=fxmacrodata&utm_content=readme
• GitHub：https://github.com/fxmacrodata/fxmacrodata
• PyPI：https://pypi.org/project/fxmacrodata/
• Readthedocs：https://fxmacrodata.readthedocs.io/en/latest/
• Zenodo：https://zenodo.org/records/18280968