fred-macro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FRED Macro — Federal Reserve Economic Data API

FRED Macro — 美联储经济数据API

API gratuita y oficial de la Reserva Federal de St. Louis (FRED) con 840,000+ series temporales macroeconómicas: PIB, inflación (CPI/PCE), tasas de interés, empleo, M2, VIX, treasuries, hipotecas y más.

Base URL:

https://api.stlouisfed.org/fred

Documentación oficial: fred.stlouisfed.org/docs/api/fred/

圣路易斯联邦储备银行（FRED）官方免费API，提供84万+宏观经济时间序列数据：GDP、通货膨胀（CPI/PCE）、利率、就业、M2、VIX、国债、抵押贷款等。

基础URL：

https://api.stlouisfed.org/fred

官方文档： fred.stlouisfed.org/docs/api/fred/

Autenticación

认证

Obtener API Key (GRATIS)

获取API密钥（免费）

Ir a: https://fred.stlouisfed.org/docs/api/api_key.html
Crear cuenta gratuita (email + contraseña)
Solicitar API key (se genera instantáneamente)
No requiere tarjeta de crédito

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

Usar la API Key

使用API密钥

python

import os
API_KEY = os.getenv("FRED_API_KEY")  # Recomendado

python

import os
API_KEY = os.getenv("FRED_API_KEY")  # 推荐方式

o directamente para pruebas:

或用于测试直接填写：

API_KEY = "TU_API_KEY_AQUI"


**⚠️ NUNCA hardcodear la API key en código compartido/commits.**

---


**⚠️ 切勿在共享代码/提交记录中硬编码API密钥。**

---

Rate Limits

请求速率限制

Límite	Valor
Requests por minuto	120 req/min
Requests por día	Ilimitado (sin límite diario explícito)
Máx observaciones por request	100,000
Máx series por request	Depende del endpoint (generalmente 1)
Costo	Completamente GRATIS

限制项	数值
每分钟请求数	120 req/min
每日请求数	无限制（无明确每日上限）
单次请求最大观测值数量	100,000
单次请求最大序列数量	取决于接口（通常为1）
费用	完全免费

Recomendaciones

建议

Cachear respuestas localmente (los datos macroeconómicos cambian con poca frecuencia)
Usar
```
observation_start
```
y
```
observation_end
```
para limitar rangos
Implementar retry con backoff si se recibe HTTP 429 (Too Many Requests)
Para descargar muchas series, intercalar 0.5s entre requests

本地缓存响应（宏观经济数据更新频率较低）
使用
```
observation_start
```
和
```
observation_end
```
限制数据范围
若收到HTTP 429（请求过多）错误，实现退避重试机制
下载大量序列时，请求间隔至少0.5秒

Endpoints Principales

主要接口

Series y Observaciones

序列与观测值

Endpoint	Descripción	Auth
`GET /fred/series/observations`	Valores históricos de una serie	API Key
`GET /fred/series/search`	Buscar series por texto	API Key
`GET /fred/series`	Metadatos de una serie	API Key
`GET /fred/series/categories`	Categorías de una serie	API Key
`GET /fred/series/release`	Release asociado a una serie	API Key

接口	描述	认证方式
`GET /fred/series/observations`	获取某一序列的历史数值	需要API密钥
`GET /fred/series/search`	按文本搜索序列	需要API密钥
`GET /fred/series`	获取某一序列的元数据	需要API密钥
`GET /fred/series/categories`	获取某一序列的分类	需要API密钥
`GET /fred/series/release`	获取某一序列对应的发布信息	需要API密钥

Categorías y Releases

分类与发布

Endpoint	Descripción
`GET /fred/category`	Información de una categoría
`GET /fred/category/children`	Subcategorías
`GET /fred/category/related`	Categorías relacionadas
`GET /fred/category/series`	Series en una categoría
`GET /fred/release`	Información de un release
`GET /fred/release/dates`	Fechas de un release
`GET /fred/release/series`	Series en un release

接口	描述
`GET /fred/category`	获取分类信息
`GET /fred/category/children`	获取子分类
`GET /fred/category/related`	获取相关分类
`GET /fred/category/series`	获取某分类下的序列
`GET /fred/release`	获取发布信息
`GET /fred/release/dates`	获取发布日期
`GET /fred/release/series`	获取某发布下的序列

Tags (etiquetas)

标签（Tags）

Endpoint	Descripción
`GET /fred/tags`	Buscar tags
`GET /fred/related_tags`	Tags relacionados
`GET /fred/tags/series`	Series con un tag específico
`GET /fred/series/tags`	Tags de una serie

接口	描述
`GET /fred/tags`	搜索标签
`GET /fred/related_tags`	获取相关标签
`GET /fred/tags/series`	获取带有指定标签的序列
`GET /fred/series/tags`	获取某序列的标签

Fuentes (Sources)

数据源（Sources）

Endpoint	Descripción
`GET /fred/sources`	Lista de fuentes de datos
`GET /fred/source`	Información de una fuente

接口	描述
`GET /fred/sources`	获取数据源列表
`GET /fred/source`	获取数据源信息

Mapas de Calendario

日历映射

Endpoint	Descripción
`GET /fred/series/updates`	Series actualizadas recientemente
`GET /fred/seasonal/adjustments`	Opciones de ajuste estacional

接口	描述
`GET /fred/series/updates`	获取近期更新的序列
`GET /fred/seasonal/adjustments`	获取季节性调整选项

Formato de Respuesta

响应格式

Por defecto devuelve XML. Se puede cambiar con

&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"
    }
  ]
}

Nota: valores
"."
indican dato no disponible (N/A).

默认返回XML格式，可通过

&file_type=json

切换为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）。

Categorías de Series

序列分类

Las series FRED están organizadas en categorías (ids numéricos):

ID	Categoría	Ejemplos
0	Todas las categorías (raíz)	—
32991	Population, Employment, & Labor Markets	UNRATE, PAYEMS, NFP
32992	National Income & Product Accounts	GDP, GDPC1, GNP
32993	Consumer Price Indexes (CPI)	CPIAUCSL, CPILFESL
32994	Producer Price Indexes (PPI)	PPIACO, PPIFIS
32995	Interest Rates	FEDFUNDS, DGS10, DGS2
32996	Money, Banking, & Finance	M2SL, M1SL, TOTBKCR
32997	International Trade	BOPGSTB
33000	U.S. Regional Data	Estadísticas estatales
33001	Academic Data	Datos académicos

Ver referencia completa en references/SERIES_REFERENCE.md.

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。

Uso Rápido

快速使用

1. Descargar una serie (Python)

1. 下载单个序列（Python）

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"])

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. Buscar series por palabra clave

2. 按关键词搜索序列

python

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)

python

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

3. Usando pandas

3. 使用pandas

python

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)

python

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)

Scripts Disponibles

可用脚本

Script	Descripción
fetch_series.py	Descarga una o más series FRED en CSV/JSON/Parquet
search_series.py	Busca series FRED por texto, categoría o tag
download_multiple.py	Descarga batches de series predefinidas por categoría

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

Series Esenciales (Headlines)

核心序列（头条数据）

Serie	Descripción	Frecuencia
`GDP`	PIB Nominal (Billions $)	Trimestral
`GDPC1`	PIB Real (Billions chained $)	Trimestral
`CPIAUCSL`	IPC General (CPI All Items)	Mensual
`CPILFESL`	IPC Subyacente (Core CPI)	Mensual
`PCEPILFE`	PCE Subyacente (Core PCE)	Mensual
`FEDFUNDS`	Tasa de Fondos Federales	Diaria
`DFF`	Tasa de Fondos Federales (efectiva)	Diaria
`DGS10`	Treasury a 10 años	Diaria
`DGS2`	Treasury a 2 años	Diaria
`T10Y2Y`	Spread 10y-2y (curva invertida)	Diaria
`UNRATE`	Tasa de Desempleo	Mensual
`PAYEMS`	Nóminas no agrícolas (Nonfarm Payrolls)	Mensual
`M2SL`	M2 Money Supply	Mensual
`M1SL`	M1 Money Supply	Mensual
`VIXCLS`	VIX (volatilidad S&P 500)	Diaria
`BAA10Y`	Spread BAA - 10y (credit spread)	Diaria
`TOTALSA`	Ventas Minoristas	Mensual
`INDPRO`	Producción Industrial	Mensual
`HOUST`	Viviendas Iniciadas	Mensual
`MORTGAGE30US`	Tasa Hipoteca 30 años	Semanal

Referencia completa: references/SERIES_REFERENCE.md (100+ series documentadas).

序列	描述	频率
`GDP`	名义GDP（十亿美元）	季度
`GDPC1`	实际GDP（十亿美元，链式计算）	季度
`CPIAUCSL`	整体消费者价格指数（CPI所有项目）	月度
`CPILFESL`	核心消费者价格指数（Core CPI）	月度
`PCEPILFE`	核心个人消费支出价格指数（Core 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+已记录序列）。

Buenas Prácticas

最佳实践

Cachear datos: los datos macro no cambian frecuentemente; guardar en Parquet/CSV local
Usar
file_type=json
: más fácil de parsear que XML
Filtrar por fecha: usar
```
observation_start
```
para evitar descargar historia innecesaria
Manejar valores
"."
: representan datos no disponibles (NaN)
Rate limiting: 120 req/min = 1 request cada 0.5s como mínimo
API Key: usar variable de entorno
```
FRED_API_KEY
```
Citar fuente: obligatorio incluir "This product uses the FRED API but is not endorsed or certified by the Federal Reserve Bank of St. Louis" en apps comerciales

缓存数据：宏观数据更新频率低，可保存为本地Parquet/CSV文件
使用
file_type=json
：比XML更易解析
按日期过滤：使用
```
observation_start
```
避免下载不必要的历史数据
处理
"."
值：代表数据不可用（对应NaN）
速率限制：120 req/min = 至少每0.5秒发起一次请求
API密钥：使用环境变量
```
FRED_API_KEY
```
存储
引用数据源：商业应用中必须包含声明："This product uses the FRED API but is not endorsed or certified by the Federal Reserve Bank of St. Louis"