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

Recomendaciones

• Cachear respuestas localmente (los datos macroeconómicos cambian con poca frecuencia)
• Usar observationstart y observationend 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

Categorías y Releases

Tags (etiquetas)

Fuentes (Sources)

Mapas de Calendario

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

Ver referencia completa en [references/SERIESREFERENCE.md](./references/SERIESREFERENCE.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

Series Esenciales (Headlines)

Referencia completa: [references/SERIESREFERENCE.md](./references/SERIESREFERENCE.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 FREDAPIKEY
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