يُعد كتاب الملاحظات Jupyter هو الأداة المفضلة للمحللين والمطورين الذين يرغبون في الجمع بين التعليمات البرمجية والبيانات والتعليقات في مستند واحد قابل للمشاركة. يقدم لك هذا الدليل سير سير العمل من نهاية إلى نهاية كامل: تثبيت FXMacroData Python SDK، وإعداد مفتاح API الخاص بك، والحصول على سلسلة مؤشرات الماكرو، وإجراء التحليل، وإنتاج الرسوم البيانية الجاهزة للنشر كل ذلك داخل دفتر ملاحظات واحد. بحلول النهاية سيكون لديك دفتر ملاحظات يعمل ويمكن إعادة إنتاجه يمكنك توسيعه مع أي من أكثر من 80 مؤشرًا يكتشفها FXMacrosData.

ما الذي ستبنيه

دفتر ملاحظات Jupyter المستقل الذي يقوم بالتحقق من صحة شخصيته مقابل FXMacroData REST API ، ويسحب سلسلة زمنية من أسعار الفائدة والتضخم لأربع عملات G10 ، ويحسب فروق أسعار الأسعار الحقيقية ، ويعرض الرسوم البيانية التفاعلية متعددة السلسلة جاهزة للمشاركة أو جدولة كتقرير متكرر.

الشروط المسبقة

بايثون 3.9 أو أحدث
يوبيتر الملاحظة أو يوبيترب تثبيت مع pip install jupyterlab
الحزم التالية: requests- لا pandas- لا matplotlib- لا seaborn
مفتاح FXMacroData API تسجيل في / اشترك للحصول على واحدة

يمكنك تثبيت كل التبعيات في أمر واحد:

pip install requests pandas matplotlib seaborn jupyterlab

ثم قم بتشغيل JupyterLab من مجلد المشروع الخاص بك:

jupyter lab

الخطوة 1 تأمين مفتاح API الخاص بك

لا تكتب أية بيانات اعتماد في ملفات المفكرة المفصلات سهلة المشاركة عن طريق الخطأ ، ويمكن إساءة استخدام مفتاح API المسرب. الطريقة الأكثر أمانًا هي تخزين المفتاح في متغير البيئة وقراءته في وقت التشغيل.

على لينكس / ماكوس، أضف هذا السطر إلى ~/.bashrc أو ~/.zshrc (ثم إعادة تشغيل المحطة أو تشغلها source ~/.bashrc):

export FXMD_API_KEY="your_actual_api_key_here"

على ويندوز (باورشل):

$env:FXMD_API_KEY = "your_actual_api_key_here"

ثم اقرأ المفتاح في أعلى دفتر الملاحظات الخاص بك في خلية إعداد مخصصة:

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

نصيحة: python-dotenv بالنسبة للأسرار على مستوى المشروع

إذا كنت تفضل .env الملف لكل مشروع، تثبيت pip install python-dotenv و أضف from dotenv import load_dotenv; load_dotenv() قبل os.environ.get() اتصلي، احتفظي بالـ .env الملف في .gitignore. .

الخطوة 2 اكتب مساعدة استرجاع قابلة لإعادة الاستخدام

كل نقطة نهاية مؤشر FXMacroData تتبع نفس بنية عنوان URL:

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

ردّة فعل (JSON) تحتوي على data صف حيث كل كائن لديه date الميدان، a val المجال، و (للوقت الدقيق) announcement_datetime المُساعد التالي يُحوّل هذه الإجابة مباشرة إلى "بانداس داتا فريم":

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)

المساعد يرفع HTTPError على 4xx/5xx الردود، يحول date عمود إلى مناسبة datetime64 نوع، ويربط علامات العملة والمؤشر مما يجعل المجموعات في الأسفل تافهة.

الخطوة الثالثة: احضر أول سلسلة

دعونا نتحقق من المساعد عن طريق جلب قرارات سعر الفائدة السياسية في الاحتياطي الفيدرالي الأمريكي منذ عام 2022:

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

يجب أن ترى إطار بيانات مع أعمدة مثل:

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

لاحظوا announcement_datetime العمود هذا يعطيك دقة الإصدار من المستوى الثاني لاستراتيجيات القائمة على الأحداث أو الاختبارات الخلفية التي تعتمد على توقيت الإعلان الدقيق. استكشاف الكتالوج الكامل للمؤشرات المتاحة في /api-data-docs/usd/policy_rate (المعدل السياسي). .

الخطوة 4 احصل على عملات متعددة

أحد الأنماط الأقوى هو سحب المؤشر نفسه لعدة عملات في وقت واحد وتجميع النتائج. الحلقة أدناه تحصل على أسعار السياسة للدولار الأمريكي واليورو والجنيه الإسترليني والدولار الأسترالي في مرة واحدة:

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)

قناع المؤشر المتاحة

فهرس المؤشرات الكامل موجود في fxmacrodata.com/api-data-docsوتشمل السلسلة الرئيسية لتحليل العملات الأجنبية policy_rate- لا inflation- لا gdp- لا unemployment- لا pmiو trade_balanceكل سلسلة تستخدم نفس نمط البحث رمز العملة المبادلة والشريحة المؤشرة.

الخطوة 5 الجمع بين مؤشرات متعددة

لحساب أسعار الفائدة الحقيقية تحتاج إلى كل من سعر الفائده والضخامة الرأسمالية لكل عملة. احضر التضخم جنبا إلى جنب مع أسعار العملة، ثم ربطها في إطار بيانات واحد نظيف:

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

الخطوة 6 إعادة تشكيل وملء للأمام

قرارات البنك المركزي نادرة تحدث 612 مرة في السنة. لتحقيق التوافق مع السلسلة الشهرية الأخرى، قم ببناء عمود تاريخ شهري وملء القيمة المعروفة الأخيرة:

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)

الخطوة 7 حساب فروق أسعار الفائدة الحقيقية

سعر الفائدة الحقيقي هو سعر السعر الرسمي للسياسة ناقص التضخم الرئيسي. يُشير الفارق الإيجابي إلى سياسة نقدية مقيدة؛ ويعني الفارقة السلبية أن البنك المركزي لا يزال متساهلاً نسبياً مع نمو أسعار المستهلك. يعد اختلافات سعر العملة EURUSD من بين أقوى المحركات المتوسطة الأجل لزوج اليورو/الدولار:

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)

الخطوة 8 تصور مع Matplotlib

مع إعداد DataFrame ، يستغرق الرسم البياني متعدد الألواح بضعة أسطر فقط. استخدم مخطط خطوة لأسعار السياسة إنها قرارات درجة منفصلة ، وليس سلسلة مستمرة:

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

نصيحة: استخدم مخططات خطوة لسلسلة أسعار الفائدة

ax.step(..., where="post") يمثل قرارات البنك المركزي بشكل صحيح كتحركات درجة منفصلة بدلا من خط متداخل سلس. ax.plot() هو مناسب.

الخطوة 9 تحقق من تقويم الإصدارات

قبل تحديد مواعيد الاسترداد المتكرر، من المفيد معرفة متى سيتم إصدار البيانات التالية. نقطة نهاية تقويم الإصدار يعيد تواريخ الإعلانات القادمة لأي عملة، حتى تتمكن من تحديد وقت تحديثات دفتر الملاحظات لتشغيل دقائق بعد كل إصدار بدلاً من الاستطلاع على جدول زمني ثابت:

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

الخطوة 10 حفظ و جدولة

لتحليل قابل للتكرار يمكنك تصدير DataFrame الواسع إلى CSV وتشغيل المفكرة على جدول زمني عبر papermill، الذي ينفذ الكتب من سطر الأوامر مع حقن المعايير:

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"

قم بتقريب هذا مع تقويم الإصدار حتى يتم تشغيل المهمة المجدولة فقط عندما تتوقع بيانات مؤشر جديدة في الواقع الحفاظ على استخدام API فعالًا في أيام النشاط المنخفض.

دفتر ملاحظات كامل في مكان واحد

كل الخلايا أعلاه تشكل دفتر ملاحظات واحد مكتمل. FXMD_API_KEY في بيئتك، وتشغيل جميع الخلايا سيكون لديك تحليل الكلي التفاعلي بالكامل في أقل من دقيقتين.

ملخص

لقد قمت ببناء سير عمل كامل في Jupyter Notebook

تحديد المصداقية مع FXMacroData بأمان عبر متغير البيئة
يطبق إعادة الاستخدام fetch_indicator() مساعد الذي يغير استجابات واجهة برمجيات التطبيقات إلى باندا DataFrames
سحب وتراكم أسعار الفائدة والسلاسل التضخمية لعدة عملات مجموعة العشرة
إعادة تشكيل بيانات البنك المركزي النادرة إلى عمود تاريخ شهري عادي مع ملء مستقبلي
يحسب فروق أسعار الفائدة الحقيقية والفوارق بين العملات
ينتج مخطط Matplotlib من ثلاث لوحات جاهز للتقارير أو المشاركة
استفسارات تقويم الإصدارات إلى وقت التجديدات المتكررة بشكل ذكي
تصدير النتائج إلى CSV وخطط تنفيذ دفتر ملاحظات مع papermill

كخطوة أخرى، قم بتوسيع دفتر الملاحظات بمجموعات FXMacroData إضافية مثل البطالة- لا ميزان التجارةو مؤشر مؤشر الأسهم لإنشاء بطاقة نتائج أكبر. fetch_indicator() مساعد وتغيير تشكيل سير العمل ينطبق دون تغيير فقط مؤشر الحلزون يحتاج إلى تحديث.

كيفية استخدام FXMacroData في دفتر ملاحظات Jupyter (من نهاية إلى نهاية)