fred-macro

FRED Macro — Federal Reserve Economic Data 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/

---

Autenticación

Obtener API Key (GRATIS)

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

Usar la API Key

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

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

---

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

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

---

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

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

Tags (etiquetas)

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

Fuentes (Sources)

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

Mapas de Calendario

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

---

Formato de Respuesta

Por defecto devuelve XML. Se puede cambiar con &file_type=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).

---

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.

---

Uso Rápido

1. Descargar una serie (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

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. Usando 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)

---

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

---

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).

---

Buenas Prácticas

1. Cachear datos: los datos macro no cambian frecuentemente; guardar en Parquet/CSV local
2. Usar file_type=json: más fácil de parsear que XML
3. Filtrar por fecha: usar observation_start para evitar descargar historia innecesaria
4. Manejar valores ".": representan datos no disponibles (NaN)
5. Rate limiting: 120 req/min = 1 request cada 0.5s como mínimo
6. API Key: usar variable de entorno FRED_API_KEY
7. 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