fred-macro

FRED Macro — Federal Reserve Economic Data API

圣路易斯联邦储备银行（FRED）提供的免费官方 API，包含 840,000+ 个宏观经济时间序列：GDP、通胀（CPI/PCE）、利率、就业、M2、VIX、美国国债、抵押贷款等。

Base URL： https://api.stlouisfed.org/fred 官方文档： fred.stlouisfed.org/docs/api/fred/

---

身份验证

获取 API Key（免费）

1. 访问：https://fred.stlouisfed.org/docs/api/api_key.html
2. 创建免费账户（邮箱 + 密码）
3. 申请 API key（立即生成）
4. 无需信用卡

使用 API Key

import os
API_KEY = os.getenv("FRED_API_KEY")  # Recomendado
# o directamente para pruebas:
# API_KEY = "TU_API_KEY_AQUI"

⚠️ 切勿将 API key 硬编码到共享代码或提交记录中。

---

速率限制

限制	值
每分钟请求数	120 req/min
每日请求数	不限（未明确设置每日上限）
每个请求的最大观测值数量	100,000
每个请求的最大序列数	取决于端点（通常为 1）
费用	完全免费

建议

• 在本地缓存响应（宏观经济数据更新频率较低）
• 使用 observation_start 和 observation_end 限定日期范围
• 如果收到 HTTP 429（请求过多），使用退避策略重试
• 下载多个序列时，每次请求间隔 0.5s

---

主要端点

序列和观测值

端点	描述	身份验证
GET /fred/series/observations	某个序列的历史值	API Key
GET /fred/series/search	按文本搜索序列	API Key
GET /fred/series	某个序列的元数据	API Key
GET /fred/series/categories	某个序列的类别	API Key
GET /fred/series/release	与某个序列关联的 release	API Key

类别和 Release

端点	描述
GET /fred/category	某个类别的信息
GET /fred/category/children	子类别
GET /fred/category/related	相关类别
GET /fred/category/series	某个类别中的序列
GET /fred/release	某个 release 的信息
GET /fred/release/dates	某个 release 的日期
GET /fred/release/series	某个 release 中的序列

Tags（标签）

端点	描述
GET /fred/tags	搜索标签
GET /fred/related_tags	相关标签
GET /fred/tags/series	带有特定标签的序列
GET /fred/series/tags	某个序列的标签

数据来源（Sources）

端点	描述
GET /fred/sources	数据来源列表
GET /fred/source	某个数据来源的信息

日历映射

端点	描述
GET /fred/series/updates	最近更新的序列
GET /fred/seasonal/adjustments	季节性调整选项

---

响应格式

默认返回 XML。可通过 &file_type=json 切换为 JSON：

{
  "realtime_start": "2026-06-01",
  "realtime_end": "2026-06-01",
  "observation_start": "1954-07-01",
  "observation_end": "2026-06-01",
  "units": "lin",
  "count": 864,
  "observations": [
    {
      "realtime_start": "2026-06-01",
      "realtime_end": "2026-06-01",
      "date": "1954-07-01",
      "value": "."
    },
    {
      "realtime_start": "2026-06-01",
      "realtime_end": "2026-06-01",
      "date": "1954-10-01",
      "value": "126.8"
    }
  ]
}

注意： "." 表示数据不可用（N/A）。

---

系列类别

FRED 系列按类别（数字 ID）组织：

ID	类别	示例
0	所有类别（根类别）	—
32991	人口、就业与劳动力市场	UNRATE, PAYEMS, NFP
32992	国民收入与产品账户	GDP, GDPC1, GNP
32993	消费者价格指数（CPI）	CPIAUCSL, CPILFESL
32994	生产者价格指数（PPI）	PPIACO, PPIFIS
32995	利率	FEDFUNDS, DGS10, DGS2
32996	货币、银行与金融	M2SL, M1SL, TOTBKCR
32997	国际贸易	BOPGSTB
33000	美国区域数据	各州统计数据
33001	学术数据	学术数据

完整参考请见 references/SERIES_REFERENCE.md。

---

快速上手

1. 下载一个系列（Python）

import requests

API_KEY = "TU_API_KEY"
url = "https://api.stlouisfed.org/fred/series/observations"
params = {
    "series_id": "GDP",
    "api_key": API_KEY,
    "file_type": "json",
    "observation_start": "2020-01-01",
    "observation_end": "2025-12-31"
}
r = requests.get(url, params=params)
data = r.json()
for obs in data["observations"]:
    if obs["value"] != ".":
        print(obs["date"], obs["value"])

2. 按关键词搜索系列

params = {
    "api_key": API_KEY,
    "file_type": "json",
    "search_text": "inflation",
    "search_type": "full_text",  # o "series_id"
    "limit": 10
}
r = requests.get("https://api.stlouisfed.org/fred/series/search", params=params)

3. 使用 pandas

import pandas as pd
import requests

def fetch_fred(series_id, api_key, start="2020-01-01"):
    url = "https://api.stlouisfed.org/fred/series/observations"
    params = {"series_id": series_id, "api_key": api_key,
              "file_type": "json", "observation_start": start}
    r = requests.get(url, params=params)
    df = pd.DataFrame(r.json()["observations"])
    df["date"] = pd.to_datetime(df["date"])
    df["value"] = pd.to_numeric(df["value"], errors="coerce")
    return df.set_index("date")["value"]

gdp = fetch_fred("GDP", API_KEY)
cpi = fetch_fred("CPIAUCSL", API_KEY)
fedfunds = fetch_fred("FEDFUNDS", API_KEY)

---

可用脚本

脚本	描述
fetch_series.py	将一个或多个 FRED 系列下载为 CSV/JSON/Parquet
search_series.py	按文本、类别或标签搜索 FRED 系列
download_multiple.py	按类别下载预定义批次的系列

---

核心系列（主要指标）

系列	描述	频率
GDP	名义 GDP（十亿美元）	季度
GDPC1	实际 GDP（链式美元，十亿美元）	季度
CPIAUCSL	整体 CPI（所有项目）	月度
CPILFESL	核心 CPI	月度
PCEPILFE	核心 PCE	月度
FEDFUNDS	联邦基金利率	日度
DFF	联邦基金有效利率	日度
DGS10	10 年期美国国债收益率	日度
DGS2	2 年期美国国债收益率	日度
T10Y2Y	10 年期与 2 年期利差（收益率曲线倒挂）	日度
UNRATE	失业率	月度
PAYEMS	非农就业人数（Nonfarm Payrolls）	月度
M2SL	M2 货币供应量	月度
M1SL	M1 货币供应量	月度
VIXCLS	VIX（标普 500 波动率）	日度
BAA10Y	BAA 与 10 年期国债利差（信用利差）	日度
TOTALSA	零售销售额	月度
INDPRO	工业生产	月度
HOUST	新屋开工数	月度
MORTGAGE30US	30 年期抵押贷款利率	周度

完整参考：references/SERIES_REFERENCE.md（记录了 100 多个系列）。

---

最佳实践

1. 缓存数据：宏观数据不会频繁变化；可保存为本地 Parquet/CSV
2. 使用 file_type=json：比 XML 更容易解析
3. 按日期筛选：使用 observation_start，避免下载不必要的历史数据
4. 处理 "." 值：表示数据不可用（NaN）
5. 速率限制：120 次请求/分钟 = 至少每 0.5 秒发送 1 次请求
6. API 密钥：使用环境变量 FRED_API_KEY
7. 注明来源：商业应用必须包含“This product uses the FRED API but is not endorsed or certified by the Federal Reserve Bank of St. Louis”