Cómo utilizar FXMacroData en un cuaderno de notas Jupyter (de extremo a extremo)

Jupyter Notebook es la herramienta de elección para analistas y desarrolladores que desean combinar código, datos y comentarios en un solo documento compartible. Esta guía lo guía a través de un flujo de trabajo completo de extremo a extremo: instalar el SDK de FXMacroData Python, configurar su clave API, obtener series de indicadores macro, realizar análisis y producir gráficos listos para publicación todo dentro de un solo cuaderno. Al final tendrá un cuader notables funcional y reproducible que puede ampliar con cualquiera de los más de 80 indicadores que FXMacrodata expone.

Los requisitos previos

• Python 3.9 o posterior
• Jupyter Notebook o JupytorLab instalar con pip install jupyterlab
• Los siguientes paquetes: requests¿ Qué ? pandas¿ Qué ? matplotlib¿ Qué ? seaborn
• Una clave de la API de FXMacroData registrarse en / suscribirse para conseguir uno

Puede instalar todas las dependencias en un solo comando:

pip install requests pandas matplotlib seaborn jupyterlab

Luego, inicie JupyterLab desde su carpeta de proyectos:

jupyter lab

Paso 1 Asegure su clave API

Nunca las credenciales de código duro en un archivo de cuaderno los cuadernos son fáciles de compartir accidentalmente, y una clave de API filtrada puede ser mal utilizada.

En Linux/macOS, añade esta línea a tu ~/.bashrc ¿ Qué ? ~/.zshrc (entonces reinicie su terminal o ejecute source ~/.bashrc):

export FXMD_API_KEY="your_actual_api_key_here"

En Windows (PowerShell):

$env:FXMD_API_KEY = "your_actual_api_key_here"

Luego lee la tecla en la parte superior de tu cuaderno en una celda de configuración dedicada:

import os

API_KEY = os.environ.get("FXMD_API_KEY")
if not API_KEY:
    raise EnvironmentError(
        "FXMD_API_KEY environment variable is not set. "
        "See https://fxmacrodata.com/subscribe to get a key."
    )

print("API key loaded ✓")

Paso 2 Escriba un ayudante de búsqueda reutilizable

Cada punto final del indicador FXMacroData sigue la misma estructura de URL:

GET https://fxmacrodata.com/api/v1/announcements/{currency}/{indicator}?api_key=YOUR_API_KEY

La respuesta JSON contiene un data matriz donde cada objeto tiene un date campo, a val campo, y (para el tiempo preciso) un announcement_datetime El siguiente ayudante convierte esa respuesta directamente en un DataFrame de pandas:

import requests
import pandas as pd

BASE_URL = "https://fxmacrodata.com/api/v1"

def fetch_indicator(currency: str, indicator: str,
                    start: str = None, end: str = None) -> pd.DataFrame:
    """Fetch a macro indicator time series from FXMacroData.

    Parameters
    ----------
    currency  : ISO currency code, e.g. 'usd', 'eur', 'gbp'
    indicator : Indicator slug, e.g. 'policy_rate', 'inflation', 'gdp'
    start     : Optional start date 'YYYY-MM-DD'
    end       : Optional end date 'YYYY-MM-DD'

    Returns
    -------
    pd.DataFrame with columns: date (datetime64), val (float64),
                                announcement_datetime (datetime64, nullable),
                                currency (str), indicator (str)
    """
    params = {"api_key": API_KEY}
    if start:
        params["start"] = start
    if end:
        params["end"] = end

    url = f"{BASE_URL}/announcements/{currency}/{indicator}"
    resp = requests.get(url, params=params, timeout=15)
    resp.raise_for_status()

    rows = resp.json().get("data", [])
    if not rows:
        return pd.DataFrame(columns=["date", "val", "announcement_datetime",
                                     "currency", "indicator"])

    df = pd.DataFrame(rows)
    df["date"] = pd.to_datetime(df["date"])
    df["val"] = pd.to_numeric(df["val"], errors="coerce")
    if "announcement_datetime" in df.columns:
        df["announcement_datetime"] = pd.to_datetime(
            df["announcement_datetime"], errors="coerce", utc=True
        )
    df["currency"] = currency.upper()
    df["indicator"] = indicator
    return df.sort_values("date").reset_index(drop=True)

El ayudante levanta un HTTPError En las respuestas 4xx/5xx, se convierte el date la columna a una correcta datetime64 El sistema de las redes de transporte de mercancías y de los servicios de transporte en línea, que se utiliza para la comunicación de datos, incluye el tipo de transporte, y coloca etiquetas de moneda e indicador haciendo triviales las uniones aguas abajo.

Paso 3 Traiga su primera serie

Verifiquemos el ayudante buscando las decisiones de la política de tasas de la Reserva Federal desde 2022:

usd_rate = fetch_indicator("usd", "policy_rate", start="2022-01-01")
usd_rate.head(10)

Deberías ver un DataFrame con columnas como:

         date   val       announcement_datetime currency    indicator
0  2022-03-16  0.25  2022-03-16T18:00:00+00:00      USD  policy_rate
1  2022-05-04  0.75  2022-05-04T18:00:00+00:00      USD  policy_rate
2  2022-06-15  1.50  2022-06-15T18:00:00+00:00      USD  policy_rate
3  2022-07-27  2.25  2022-07-27T18:00:00+00:00      USD  policy_rate
...

¿ Se fijan en el ? announcement_datetime columna esto le da precisión de lanzamiento de segundo nivel para estrategias basadas en eventos o backtests que dependen del momento exacto del anuncio. /api-data-docs/usd/taxa de política- ¿ Qué ?

Paso 4 Obtener varias monedas

Uno de los patrones más poderosos es tirar del mismo indicador para varias monedas simultáneamente y apilar los resultados.

currencies = ["usd", "eur", "gbp", "aud"]
START = "2022-01-01"

policy_rates = pd.concat(
    [fetch_indicator(ccy, "policy_rate", start=START) for ccy in currencies],
    ignore_index=True
)

print(f"Fetched {len(policy_rates)} rows across {policy_rates['currency'].nunique()} currencies")
policy_rates.groupby("currency").tail(2)

Paso 5 Combinar varios indicadores

Para calcular las tasas de interés reales se necesita tanto la tasa de interés y la inflación global para cada moneda.

inflation = pd.concat(
    [fetch_indicator(ccy, "inflation", start=START) for ccy in currencies],
    ignore_index=True
)

# Stack all observations into one long-form DataFrame
macro = pd.concat([policy_rates, inflation], ignore_index=True)
print(macro.groupby(["currency", "indicator"]).size().to_string())

Paso 6 Reforma y relleno de la caja

Las decisiones del banco central son escasas ocurren 612 veces al año. Para alinearlas con otras series mensuales, construye una columna vertebral de fechas mensuales y rellena hacia adelante el último valor conocido:

import numpy as np

# Floor each observation to month start for alignment
macro["month"] = macro["date"].dt.to_period("M").dt.to_timestamp()

# Pivot to wide: one column per currency+indicator combination
wide = (
    macro
    .groupby(["month", "currency", "indicator"])["val"]
    .last()                          # latest reading within the month
    .unstack(["currency", "indicator"])
)

# Build a complete monthly date spine and forward-fill
date_spine = pd.date_range(START, pd.Timestamp.today(), freq="MS")
wide = wide.reindex(date_spine).ffill()

wide.tail(3)

Paso 7 Calcular los diferenciales de tipos reales

Un diferencial de tipo de interés real es el tipo de cambio nominal menos la inflación general. Un diferente positivo indica una política monetaria restrictiva; un diferencial negativo significa que el banco central sigue siendo acomodaticio en relación con el crecimiento de los precios al consumidor.

for ccy in [c.upper() for c in currencies]:
    try:
        wide[(ccy, "real_rate")] = (
            wide[(ccy, "policy_rate")] - wide[(ccy, "inflation")]
        )
    except KeyError:
        pass  # skip if either series is missing

# EUR minus USD real rate differential
wide[("spread", "eur_usd")] = (
    wide[("EUR", "real_rate")] - wide[("USD", "real_rate")]
)

wide[[("USD", "real_rate"), ("EUR", "real_rate"), ("spread", "eur_usd")]].tail(6)

Paso 8 Visualizar con Matplotlib

Con el DataFrame listo, un gráfico de múltiples paneles toma sólo unas pocas líneas.

import matplotlib.pyplot as plt
import matplotlib.dates as mdates

fig, axes = plt.subplots(3, 1, figsize=(13, 11), sharex=True)
fig.patch.set_facecolor("#F8FAFC")

COLORS = {"USD": "#2563EB", "EUR": "#16A34A", "GBP": "#7C3AED", "AUD": "#F97316"}

# Panel 1: Policy rates
ax1 = axes[0]
for ccy in [c.upper() for c in currencies]:
    try:
        series = wide[(ccy, "policy_rate")].dropna()
        ax1.step(series.index, series.values, where="post",
                 label=ccy, color=COLORS[ccy], linewidth=1.8)
    except KeyError:
        pass
ax1.set_ylabel("Policy rate (%)")
ax1.set_title("Central Bank Policy Rates — G4", fontweight="bold")
ax1.legend(loc="upper left", fontsize=9)
ax1.grid(axis="y", alpha=0.3)

# Panel 2: Real rates
ax2 = axes[1]
for ccy in [c.upper() for c in currencies]:
    try:
        series = wide[(ccy, "real_rate")].dropna()
        ax2.plot(series.index, series.values,
                 label=ccy, color=COLORS[ccy], linewidth=1.8)
    except KeyError:
        pass
ax2.axhline(0, color="#94A3B8", linewidth=0.8, linestyle="--")
ax2.set_ylabel("Real rate (%)")
ax2.set_title("Real Interest Rates (Policy Rate − Inflation)", fontweight="bold")
ax2.legend(loc="upper left", fontsize=9)
ax2.grid(axis="y", alpha=0.3)

# Panel 3: EUR–USD spread
ax3 = axes[2]
spread = wide[("spread", "eur_usd")].dropna()
ax3.fill_between(spread.index, spread.values, 0,
                  where=spread.values >= 0,
                  color="#16A34A", alpha=0.30, label="EUR favoured")
ax3.fill_between(spread.index, spread.values, 0,
                  where=spread.values < 0,
                  color="#2563EB", alpha=0.30, label="USD favoured")
ax3.plot(spread.index, spread.values, color="#374151", linewidth=1.6)
ax3.axhline(0, color="#94A3B8", linewidth=0.8, linestyle="--")
ax3.set_ylabel("Spread (pp)")
ax3.set_title("EUR−USD Real Rate Differential", fontweight="bold")
ax3.legend(loc="upper left", fontsize=9)
ax3.grid(axis="y", alpha=0.3)

ax3.xaxis.set_major_formatter(mdates.DateFormatter("%b %Y"))
ax3.xaxis.set_major_locator(mdates.MonthLocator(interval=4))
plt.setp(ax3.xaxis.get_majorticklabels(), rotation=30, ha="right")

fig.tight_layout(h_pad=1.6)
plt.savefig("macro_analysis.png", dpi=150, bbox_inches="tight")
plt.show()

Paso 9 Revisa el calendario de las ediciones

Antes de programar las búsquedas recurrentes, es útil saber exactamente cuándo se deben publicar los próximos datos. punto final del calendario de liberación devuelve las fechas de anuncio próximas para cualquier moneda, para que pueda programar las actualizaciones de su cuaderno para que se ejecuten minutos después de cada lanzamiento en lugar de votar en un horario fijo:

def fetch_calendar(currency: str) -> pd.DataFrame:
    """Fetch upcoming release dates for a currency from the FXMacroData calendar."""
    url = f"{BASE_URL}/calendar/{currency}"
    resp = requests.get(url, params={"api_key": API_KEY}, timeout=15)
    resp.raise_for_status()
    events = resp.json().get("data", [])
    df = pd.DataFrame(events)
    if df.empty:
        return df
    df["release_date"] = pd.to_datetime(df["release_date"], errors="coerce")
    return df.sort_values("release_date").reset_index(drop=True)

# Upcoming USD releases
usd_calendar = fetch_calendar("usd")
upcoming = usd_calendar[usd_calendar["release_date"] >= pd.Timestamp.today()]
print(upcoming[["release_date", "indicator"]].head(10).to_string(index=False))

Paso 10 Guardar y programar

Para un análisis repetible puede exportar el DataFrame ancho a CSV y ejecutar el cuaderno de notas en un horario a través de papermill, que ejecuta las libretas desde la línea de comandos con la inyección de parámetros:

pip install papermill

# At the end of your notebook: persist the dataset
wide.to_csv("macro_data.csv")
print(f"Saved {wide.shape[0]} rows × {wide.shape[1]} columns to macro_data.csv")

# Execute the notebook from the command line (e.g. from cron or a CI job)
papermill macro_analysis.ipynb macro_analysis_output.ipynb \
  -p START "2022-01-01"

Apare esto con el calendario de lanzamiento para que su trabajo programado solo se ejecute cuando se esperan nuevos datos de indicadores manteniendo el uso de la API eficiente en los días de baja actividad.

Resumen de las actividades

Ha creado un flujo de trabajo completo de Jupyter Notebook que:

• Se autentica con FXMacroData de forma segura a través de una variable de entorno
• Implementa un sistema reutilizable fetch_indicator() ayudante que convierte las respuestas de API a pandas DataFrames
• Las series de tipos de interés y de inflación de las monedas del G10
• Reforma de los datos escasos del banco central en una columna de fecha mensual regular con relleno a plazo
• Calcula los diferenciales de tipos reales y los diferencia les entre divisas
• Produce un gráfico Matplotlib de tres paneles listo para informes o compartir
• Consulta el calendario de lanzamiento para actualizar de forma inteligente
• Exporta resultados a CSV y programa la ejecución de cuadernos con papermill

Como siguiente paso, extienda el cuaderno con series adicionales de FXMacroData como el desempleo¿ Qué ? Balanza comercial, y PMI Para construir una tarjeta de puntuación macro más completa. fetch_indicator() sólo el slug del indicador necesita actualización.