Comment utiliser FXMacroData dans un bloc-notes Jupyter (de bout en bout)

Jupyter Notebook est l'outil de choix pour les analystes et les développeurs qui souhaitent combiner le code, les données et les commentaires dans un seul document partageable. Ce guide vous guide à travers un flux de travail complet de bout en bout: installer le SDK Python FXMacroData, configurer votre clé API, récupérer des séries d'indicateurs macro, effectuer des analyses et produire des graphiques prêts à être publiés le tout dans un même bloc-notes. À la fin, vous aurez un bloc-note fonctionnel et reproductible que vous pouvez étendre avec l'un des plus de 80 indicateurs exposés par FXMacrodata.

Pré-requis

• Python 3.9 ou ultérieur
• Jupyter Notebook ou JupytorLab installer avec pip install jupyterlab
• Les paquets suivants: requestsJe suis désolé . pandasJe suis désolé . matplotlibJe suis désolé . seaborn
• Une clé d'API FXMacroData inscrivez-vous à / souscrivez Pour en avoir un

Vous pouvez installer toutes les dépendances en une seule commande:

pip install requests pandas matplotlib seaborn jupyterlab

Ensuite lancez JupyterLab depuis votre dossier de projet:

jupyter lab

Étape 1 Sécurisez votre clé API

Ne jamais utiliser de code dur dans un fichier de bloc-notes les blocs-notés sont faciles à partager accidentellement, et une clé API fuite peut être utilisée à mauvais escient.

Sur Linux/macOS, ajoutez cette ligne à votre ~/.bashrc ou ... ~/.zshrc (alors redémarrez votre terminal ou exécutez source ~/.bashrc):

export FXMD_API_KEY="your_actual_api_key_here"

Dans Windows (PowerShell):

$env:FXMD_API_KEY = "your_actual_api_key_here"

Ensuite, lisez la clé en haut de votre bloc-notes dans une cellule de configuration dédiée:

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

Étape 2 Écrire un assistant de récupération réutilisable

Chaque indicateur FXMacroData est basé sur la même structure d'URL:

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

La réponse JSON contient un data une matrice où chaque objet a un date le champ, un val Le champ de travail est de l'ordre de: announcement_datetime L'assistant suivant convertit cette réponse directement en un Panda DataFrame:

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)

L' aide soulève un HTTPError sur les réponses 4xx/5xx, convertit le date Une colonne à droite. datetime64 Les étiquettes de monnaie et d'indicateur sont ajoutées, rendant les joints en aval triviaux.

Étape 3 Apportez votre première série

Vérifions l'assistant en récupérant les décisions de la Réserve fédérale américaine sur les taux de référence depuis 2022:

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

Vous devriez voir une DataFrame avec des colonnes comme:

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

Vous avez remarqué ? announcement_datetime Cette fonctionnalité vous permet de vérifier la précision de la publication de la deuxième phase pour les stratégies basées sur des événements ou les backtests qui dépendent du calendrier exact des annonces. /api-data-docs/usd/taux de la politiqueJe suis désolé .

Étape 4 Récupérer plusieurs devises

L'un des modèles les plus puissants consiste à tirer le même indicateur pour plusieurs devises simultanément et à empiler les résultats.

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)

Étape 5 Combiner plusieurs indicateurs

Pour calculer les taux d'intérêt réels, vous avez besoin à la fois du taux directeur et de l'inflation globale pour chaque devise.

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

Étape 6 Remodeler et remplir

Les décisions de la banque centrale sont rares elles se produisent 612 fois par an. Pour les aligner sur les autres séries mensuelles, construisez une colonne vertébrale de date mensuelle et remplissez en avant la dernière valeur connue:

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)

Étape 7 Calculer les écarts de taux réels

Un taux réel est le taux directeur nominal moins l'inflation globale. Un écart positif indique une politique monétaire restrictive; un écart négatif signifie que la banque centrale est toujours accommodante par rapport à la croissance des prix à la consommation.

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)

Étape 8 Visualisez avec Matplotlib

Avec le DataFrame prêt, un graphique multi-paneau ne prend que quelques lignes.

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

Étape 9 Vérifiez le calendrier des sorties

Avant de planifier des récupérations récurrentes, il est utile de savoir exactement quand les prochaines versions de données sont attendues. point final du calendrier de sortie renvoie les dates d'annonce à venir pour n'importe quelle devise, de sorte que vous pouvez programmer vos mises à jour de bloc-notes à quelques minutes après chaque sortie plutôt que de faire des sondages selon un calendrier fixe:

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

Étape 10 Enregistrer et planifier

Pour une analyse répétable, vous pouvez exporter le large DataFrame vers CSV et exécuter le bloc-notes sur un calendrier via papermill, qui exécute les carnets de notes à partir de la ligne de commande avec l'injection de paramètres:

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"

Associer cela au calendrier de sortie afin que votre travail programmé ne s'exécute que lorsque de nouvelles données d'indicateur sont réellement attendues maintenir l'utilisation efficace de l'API les jours de faible activité.

Résumé

Vous avez créé un flux de travail complet de Jupyter Notebook qui:

• Authentifie avec FXMacroData en toute sécurité via une variable d'environnement
• Il met en œuvre un système réutilisable. fetch_indicator() aide qui convertit les réponses API en pandas DataFrames
• Séries de taux de référence et d' inflation pour plusieurs monnaies du G10
• Ressemble les données de banque centrale rares sur une colonne vertébrale de date mensuelle régulière avec remplissage à terme
• Calcule les écarts de taux réels et les différentiels entre devises
• Produit un tableau Matplotlib à trois panneaux prêt pour les rapports ou le partage
• Recherche le calendrier de sortie à l'heure des mises à jour récurrentes intelligemment
• Exporte les résultats vers CSV et calendrier de l'exécution de cahier avec papermill

Dans l'étape suivante, élargissez le bloc-notes avec des séries FXMacroData supplémentaires telles que le chômageJe suis désolé . la balance commerciale, et PMI Pour construire une carte de pointage macro plus complète. fetch_indicator() seulement le slug de l'indicateur doit être mis à jour.