Como usar FXMacroData em um bloco de notas Jupyter (End-to-End)

O Jupyter Notebook é a ferramenta de escolha para analistas e desenvolvedores que desejam combinar código, dados e comentários em um único documento compartilhável. Este guia o guia através de um fluxo de trabalho completo de ponta a ponta: instalação do FXMacroData Python SDK, configuração de sua chave API, busca de séries de indicadores de macro, execução de análise e produção de gráficos prontos para publicação tudo dentro de um único notebook. No final, você terá um notebook funcional e reprodutível que pode ser ampliado com qualquer um dos mais de 80 indicadores que o FXMacrodata expõe.

Requisitos prévios

• Python 3.9 ou posterior
• Jupyter Notebook ou JupytorLab instalar com pip install jupyterlab
• Os seguintes pacotes: requests- Não . pandas- Não . matplotlib- Não . seaborn
• Uma chave da API do FXMacroData registe-se em / subscrever para conseguir uma

Pode instalar todas as dependências num comando:

pip install requests pandas matplotlib seaborn jupyterlab

Em seguida, inicie o JupyterLab da sua pasta de projetos:

jupyter lab

Passo 1 Proteja sua chave API

Nunca use credenciais de código rígido em um arquivo de notebook os notebooks são fáceis de compartilhar acidentalmente, e uma chave de API vazada pode ser mal utilizada.

No Linux/macOS, adicione esta linha ao seu ~/.bashrc Ou ... ~/.zshrc (e reinicia o terminal ou executa source ~/.bashrc):

export FXMD_API_KEY="your_actual_api_key_here"

No Windows (PowerShell):

$env:FXMD_API_KEY = "your_actual_api_key_here"

Então leia a chave no topo do seu bloco de notas em uma célula de configuração 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 ✓")

Passo 2 Escreva um auxiliar de busca reutilizável

Cada ponto final do indicador FXMacroData segue a mesma estrutura de URL:

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

A resposta JSON contém um data matriz onde cada objeto tem um date campo, um val campo, e (para o calendário preciso) um announcement_datetime O assistente seguinte converte essa resposta diretamente em um DataFrame panda:

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)

O ajudante levanta um HTTPError No caso das respostas 4xx/5xx, converte o date coluna para um adequado datetime64 O sistema de ligação é um sistema de transmissão de dados que permite a ligação de dados de uma moeda e de um indicador.

Passo 3 Traga sua primeira série

Vamos verificar o ajudante, procurando as decisões de política de taxas da Reserva Federal dos EUA desde 2022:

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

Você deve ver um DataFrame com colunas 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
...

Reparem no ... announcement_datetime coluna que lhe dá a precisão de lançamento de segundo nível para estratégias orientadas por eventos ou backtests que dependem do calendário exato de anúncio. /api-data-docs/usd/policy_rate- Não .

Passo 4 Obter várias moedas

Um dos padrões mais poderosos é puxar o mesmo indicador para várias moedas simultaneamente e empilhar os 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)

Passo 5 Combinar múltiplos indicadores

Para calcular as taxas de juros reais, você precisa tanto da taxa de juras e inflação global para cada moeda.

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

Passo 6 Reforma e preenchimento

Para alinhá-los com outras séries mensais, construir uma coluna de data mensal e preencher o último valor conhecido:

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)

Passo 7 Cálculo dos diferenciais de taxa real

A taxa real é a taxa nominal de política menos a inflação nominal. Um spread positivo sinaliza uma política monetária restritiva; um spread negativo significa que o banco central ainda é acomodativo em relação ao crescimento dos preços ao 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)

Passo 8 Visualize com o Matplotlib

Com o DataFrame pronto, um gráfico de vários painéis leva apenas algumas linhas.

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

Passo 9 Verifique o calendário de lançamentos

Antes de programar buscas recorrentes, é útil saber exatamente quando as próximas publicações de dados devem ser feitas. ponto final do calendário de liberação Retorna datas de anúncio próximas para qualquer moeda, para que você possa cronometrar suas atualizações de notebook para executar minutos após cada lançamento, em vez de pesquisar em um cronograma fixo:

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

Passo 10 Salvar e agendar

Para uma análise repetível, pode exportar o DataFrame amplo para CSV e executar o bloco de notas num cronograma através do papermill, que executa blocos de notas a partir da linha de comando com injeção 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"

Emparelhe isso com o calendário de lançamento para que seu trabalho programado só seja executado quando novos dados de indicadores forem realmente esperados mantendo o uso de API eficiente nos dias de baixa atividade.

Resumo

Você criou um fluxo de trabalho completo do Jupyter Notebook que:

• Atenta com FXMacroData de forma segura através de uma variável de ambiente
• Implementa um reutilizável fetch_indicator() auxiliar que converte respostas de API para pandas DataFrames
• Série de taxas de juro e de inflação de política monetária e de empilhadeiras para várias moedas do G10
• Reforma de dados escassos do banco central numa coluna de datas regulares mensalmente com preenchimento a prazo
• Calcula os spreads de taxas reais e os diferenciais entre moedas
• Produz um gráfico Matplotlib de três painéis pronto para relatórios ou compartilhamento
• Pergunta o calendário de lançamento para atualizar de forma inteligente
• Exporta resultados para CSV e execução de agenda de blocos de notas com papermill

Como passo seguinte, estenda o bloco de notas com séries adicionais FXMacroData como desemprego- Não . Balança comercialE ... PMI Para construir um mapa de resultados macro mais completo. fetch_indicator() apenas a barra de indicadores precisa de atualização.