Cara Menggunakan FXMacroData di Jupyter Notebook (End-to-End)

Jupyter Notebook adalah alat pilihan bagi analis dan pengembang yang ingin menggabungkan kode, data, dan komentar dalam satu dokumen yang dapat dibagikan. Panduan ini memandu Anda melalui alur kerja end-to-end lengkap: menginstal FXMacroData Python SDK, mengatur kunci API Anda, mengambil seri indikator makro, melakukan analisis, dan menghasilkan grafik siap publikasi semua di dalam satu notebook. Pada akhirnya Anda akan memiliki buku catatan yang berfungsi, dapat direproduksi yang dapat Anda perluas dengan 80+ indikator yang diungkapkan FXMacrodata.

Persyaratan

• Python 3.9 atau lebih baru
• Jupyter Notebook atau JupytorLab install dengan pip install jupyterlab
• Paket berikut: requestsAku akan pergi. pandasAku akan pergi. matplotlibAku akan pergi. seaborn
• Kunci API FXMacroData daftar di /langganan untuk mendapatkan satu

Anda dapat menginstal semua ketergantungan dengan satu perintah:

pip install requests pandas matplotlib seaborn jupyterlab

Kemudian buka JupyterLab dari folder proyek Anda:

jupyter lab

Langkah 1 Amankan Kunci API Anda

Jangan pernah hard-code kredensial di file notebook notebook mudah untuk berbagi secara tidak sengaja, dan key API bocor dapat disalahgunakan.

Pada Linux/macOS, tambahkan baris ini ke ~/.bashrc atau ~/.zshrc (lalu restart terminal atau run source ~/.bashrc):

export FXMD_API_KEY="your_actual_api_key_here"

Pada Windows (PowerShell):

$env:FXMD_API_KEY = "your_actual_api_key_here"

Kemudian baca kunci di bagian atas buku catatan Anda di sel pengaturan khusus:

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

Langkah 2 Tuliskan Pembantu Mengambil yang Dapat Digunakan Lagi

Setiap titik akhir indikator FXMacroData mengikuti struktur URL yang sama:

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

Jawaban JSON berisi data array dimana setiap objek memiliki date lapangan, a val lapangan, dan (untuk waktu yang tepat) announcement_datetime Pembantu berikut mengubah respon itu langsung ke dalam Pandas 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)

Pembantu mengangkat HTTPError pada 4xx/5xx respon, mengkonversi date kolom ke yang tepat datetime64 membuat sambungan hilir tidak penting.

Langkah 3 Ambil Seri Pertama Anda

Mari kita verifikasi pembantu dengan mengambil keputusan kebijakan suku bunga US Federal Reserve sejak 2022:

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

Anda harus melihat DataFrame dengan kolom seperti:

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

Perhatikan announcement_datetime kolom ini memberi Anda tingkat kedua presisi rilis untuk strategi yang didorong oleh peristiwa atau backtest yang bergantung pada waktu pengumuman yang tepat. /api-data-docs/usd/policy_rateAku tidak tahu.

Langkah 4 Dapatkan Beberapa Mata Uang

Salah satu pola yang paling kuat adalah menarik indikator yang sama untuk beberapa mata uang secara bersamaan dan menumpuk hasilnya.

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)

Langkah 5 Gabungkan beberapa indikator

Untuk menghitung suku bunga riil Anda perlu baik tingkat kebijakan dan inflasi utama untuk setiap mata uang.

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

Langkah 6 Membuat ulang dan mengisi ke depan

Keputusan bank sentral jarang terjadi mereka terjadi 6 12 kali setahun. Untuk menyelaraskan mereka dengan seri bulanan lainnya, bangun tulang belakang tanggal bulanan dan mengisi ke depan nilai terakhir yang diketahui:

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)

Langkah 7 Menghitung Spread Tarif Nyata

Nilai real adalah nilai nominal kebijakan dikurangi inflasi nominal. Spread positif menandakan kebijakan moneter yang restriktif; spread negatif berarti bank sentral masih akomodatif relatif terhadap pertumbuhan harga konsumen.

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)

Langkah 8 Visualisasikan dengan Matplotlib

Dengan DataFrame siap, grafik multi-panel hanya membutuhkan beberapa baris.

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

Langkah 9 Periksa Kalender Rilis

Sebelum menjadwalkan pengambilan berulang, berguna untuk mengetahui persis kapan rilis data berikutnya. Tanggal akhir rilis mengembalikan tanggal pengumuman mendatang untuk mata uang apa pun, sehingga Anda dapat mengatur waktu pembaruan buku catatan Anda untuk berjalan beberapa menit setelah setiap rilis daripada jajak pendapat pada jadwal tetap:

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

Langkah 10 Simpan dan Jadwalkan

Untuk analisis yang dapat diulang Anda dapat mengekspor DataFrame lebar ke CSV dan menjalankan buku catatan pada jadwal melalui papermill, yang menjalankan notebook dari baris perintah dengan injeksi parameter:

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"

Pasangkan ini dengan kalender rilis sehingga pekerjaan yang dijadwalkan hanya berjalan ketika data indikator baru benar-benar diharapkan menjaga penggunaan API efisien pada hari-hari aktivitas rendah.

Ringkasan

Anda telah membangun alur kerja Jupyter Notebook yang lengkap yang:

• Memotentikasi dengan FXMacroData dengan aman melalui variabel lingkungan
• Mengimplementasikan reusable fetch_indicator() helper yang mengkonversi respon API ke panda DataFrames
• Pulls and stacks rate kebijakan dan inflasi seri untuk beberapa mata uang G10
• Mengubah data bank sentral yang jarang ke dalam tulang belakang tanggal bulanan reguler dengan pengisian terdepan
• Menghitung spread suku bunga riil dan diferensial lintas mata uang
• Membuat grafik Matplotlib tiga panel siap untuk laporan atau berbagi
• Pertanyaan kalender rilis untuk waktu berulang refresh secara cerdas
• Ekspor hasil ke CSV dan jadwal notebook eksekusi dengan papermill

Sebagai langkah selanjutnya, perluas buku catatan dengan seri FXMacroData tambahan seperti pengangguranAku akan pergi. neraca perdagangan, dan PMI untuk membangun kartu skor makro yang lebih lengkap. fetch_indicator() hanya slug indikator perlu diperbarui.