Forecasting Macro Releases: How to Use the FXMacroData Predictions API

لماذا التوقعات مهمة بقدر ما هو الرقم نفسه

أسواق العملات الأجنبية لا تتحرك على إصدارات البيانات إنها تتحركة على مفاجآت. الاحتياطي الفيدرالي أو البنك المركزي الأوروبي إذا كان الرقم يطابق الإجماع، فإن الزوج بالكاد يتقلق، إذا انحرف، ستحصل على ارتفاع.

هذه الفجوة المسافة بين ما كان متوقعا وما وصل هي حيث يعيش جزء كبير من تقلبات العملات الأجنبية. للعمل معها بشكل منهجي، تحتاج إلى الوصول إلى التنبؤ جنبا إلى جنب مع الملاحظة الفعلية، مرتبطة معا بطريقة تسمح لك بحساب المفاجأة دون تلوث بياناتك مع lookahead.

تم بناء واجهة برمجة برمجة التنبؤات FXMacroData لهذا التدفق بالضبط. فإنه يظهر التنبعات من خمس فئات مصدر متميزة ويربط كل توقعات إلى إعلان الهدف من خلال مستقر announcement_id، حتى تتمكن من ربط التنبؤات مع القيم المحققة، وقياس دقة التنبأ مع مرور الوقت، وبناء مؤشرات مفاجأة لأي مؤشر ومزيج العملات التي تهتم بها.

ما يعيد نقطة النهاية التنبؤات

هناك طريقتان للكشف عن بيانات التنبؤ:

• /api/v1/predictions/{currency} جميع التوقعات لعملة، عبر كل مؤشر في الكتالوج، مع مرشحات اختيارية للمؤشر، ونوع التنبؤ، والمصدر.
• /api/v1/predictions/{currency}/{indicator} جميع التوقعات لزوج عملات ومؤشر معين.

كلا الطرق مجانية للدولار الأمريكي. العملات غير الدولار الأمريكى تتطلب مفتاح API المهني.

المجموعات الردّية تدخل بإعلان. announcement_id مفتاح ثابت و محدد في الشكل {currency}_{indicator}_{date} تليها predictions قائمة حيث يحتوي كل إدخال على القيمة المتوقعة، ومصدرها، وسمعة قابلة للقراءة من قبل الإنسان. التضخم بالدولار:

{
  "currency": "USD",
  "indicator": "inflation",
  "count": 2,
  "prediction_count": 3,
  "data": [
    {
      "announcement_id": "usd_inflation_2026-02-28",
      "currency": "usd",
      "indicator": "inflation",
      "date": "2026-02-28",
      "announcement_datetime": 1772433000,
      "predictions": [
        {
          "predicted_value": 2.9,
          "prediction_type": "market_consensus",
          "prediction_source": "philly_fed_spf",
          "prediction_source_label": "Philadelphia Fed Survey of Professional Forecasters"
        }
      ]
    },
    {
      "announcement_id": "usd_inflation_2026-03-31",
      "currency": "usd",
      "indicator": "inflation",
      "date": "2026-03-31",
      "predictions": [
        {
          "predicted_value": 2.6,
          "prediction_type": "market_consensus",
          "prediction_source": "philly_fed_spf",
          "prediction_source_label": "Philadelphia Fed Survey of Professional Forecasters"
        },
        {
          "predicted_value": 2.5,
          "prediction_type": "imf_weo",
          "prediction_source": "imf_weo",
          "prediction_source_label": "IMF World Economic Outlook"
        }
      ]
    }
  ]
}

- ... announcement_id على كل صف التنبؤ هو نفس الصف الذي أعاده /api/v1/announcements/{currency}/{indicator}، لذا فإن المجموعة البسيطة للمعجم هي كل ما تحتاجه لربط كل توقعات مع ملاحظتها المحققة.

فئات مصادر التنبؤ

خمسة prediction_type فمفهوم الفرق مهم لكيفية قياس وتفسير كل توقعات:

كل مصدر يخدم غرض تحليلي مختلف. توافق السوق هو توقعات السوق على الأفق القصير التي تدفع رد فعل العملات الأجنبية الفوري في يوم الإصدار. تعكس توقعات البنك المركزي آفاق المؤسسة الخاصة وتكون مفيدة لتتبع مدى تطور توقعات المصرف بين الاجتماعات. توفر توقعات IMF WEO خط أساس محايد متعدد السنوات وهي متسقة عبر جميع العملات 18 المغطاة، مما يجعلها مفيدة للمقارنات بين العملات.

بناء مؤشر مفاجأة في بايثون

التطبيق الأكثر مباشرة لـ API التنبؤات هو حساب مؤشر المفاجأة الإصدارية انحراف الطباعة الفعلية من توقعات السوق ، والتي يتم التعبير عنها في الانحرافات القياسية للمفاجآت التاريخية. هنا مثال كامل ل الرواتب غير الزراعية في الولايات المتحدة:

import requests
import statistics

BASE = "https://fxmacrodata.com/api"

# Fetch predictions — free for USD, no key needed
preds_resp = requests.get(
    f"{BASE}/v1/predictions/usd/non_farm_payrolls",
    params={"prediction_type": "market_consensus"},
    timeout=30,
).json()

# Fetch actuals
actuals_resp = requests.get(
    f"{BASE}/v1/announcements/usd/non_farm_payrolls",
    params={"start_date": "2020-01-01"},
    timeout=30,
).json()

# Index actuals by announcement_id
actuals = {row["announcement_id"]: row["val"] for row in actuals_resp["data"]}

# Compute surprises (actual - consensus)
surprises = []
for group in preds_resp["data"]:
    aid = group["announcement_id"]
    actual = actuals.get(aid)
    if actual is None:
        continue
    # Use the first (or only) prediction in the group
    forecast = group["predictions"][0]["predicted_value"]
    surprises.append({
        "date": group["date"],
        "actual": actual,
        "forecast": forecast,
        "surprise": actual - forecast,
    })

# Normalise to z-scores
values = [s["surprise"] for s in surprises]
mean = statistics.mean(values)
stdev = statistics.stdev(values)
for s in surprises:
    s["z_score"] = (s["surprise"] - mean) / stdev

# Print recent surprises
for s in surprises[-6:]:
    direction = "↑ beat" if s["z_score"] > 0 else "↓ miss"
    print(f"{s['date']}: actual={s['actual']:,.0f}k  forecast={s['forecast']:,.0f}k  "
          f"surprise={s['surprise']:+,.0f}k  z={s['z_score']:+.2f}  {direction}")

يمنحك الناتج سلسلة زمنية من المفاجآت المطبقة التي يمكن أن ترتبط مباشرة مع تحركات USD الفورية في أيام الإصدار لتحديد معامل انتقال المفجأة إلى FX لأي مؤشر معين.

مقارنة توقعات البنك المركزي بتوافق الآراء في السوق

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

يمكنك استرجاع كلا نوعي التنبؤات في طلب واحد وحساب الاختلاف مباشرة:

import requests

# Fetch all prediction types for EUR inflation together
resp = requests.get(
    "https://fxmacrodata.com/api/v1/predictions/eur/inflation",
    params={"api_key": "YOUR_API_KEY"},
    timeout=30,
).json()

# For each announcement group, compare central_bank_forecast vs market_consensus
for group in resp["data"]:
    preds_by_type = {p["prediction_type"]: p for p in group["predictions"]}
    cb = preds_by_type.get("central_bank_forecast")
    mkt = preds_by_type.get("market_consensus")
    if cb and mkt:
        divergence = cb["predicted_value"] - mkt["predicted_value"]
        print(f"{group['date']}: CB={cb['predicted_value']:.2f}%  "
              f"Market={mkt['predicted_value']:.2f}%  "
              f"Divergence={divergence:+.2f}pp  "
              f"({cb['prediction_source_label']})")

الاختلاف الإيجابي (البنك المركزي يتنبأ بتضخم أعلى من السوق) هو عادة إشارة صقورية. إما أن البنك لديه معلومات غير عامة أو يشير عمدا إلى التسامح مع التضخام فوق الهدف. سبق الاختلف الإيجابية المستدامة تاريخياً ارتفاعات مفاجئة في العديد من أزواج العملات التي تتبع على تقويم الإصدار. .

مقارنة توقعات العملات مع WEO الصندوق

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

import requests

API_KEY = "YOUR_API_KEY"
CURRENCIES = ["aud", "cad", "nzd", "brl"]

forecasts = {}
for ccy in CURRENCIES:
    resp = requests.get(
        f"https://fxmacrodata.com/api/v1/predictions/{ccy}/gdp",
        params={"prediction_type": "imf_weo", "api_key": API_KEY},
        timeout=30,
    ).json()
    if resp.get("data"):
        # Take the most recent forecast
        latest = resp["data"][-1]
        forecasts[ccy.upper()] = latest["predictions"][0]["predicted_value"]

# Rank by projected growth
ranked = sorted(forecasts.items(), key=lambda x: x[1], reverse=True)
print("IMF WEO GDP forecast ranking:")
for rank, (ccy, val) in enumerate(ranked, 1):
    print(f"  {rank}. {ccy}: {val:.1f}% YoY")

هذا النوع من الترتيب يغذى بشكل طبيعي في أطر القيمة النسبية لأزواج العملات السلعية مثل AUD / CAD أو NZD / AUD ، حيث تكون فروق النمو محركًا رئيسيًا لموقف الحمل على المدى المتوسط.

تصفية حسب مصدر التنبؤ

عندما يكون للإعلان الواحد توقعات متعددة من مصادر مختلفة، قد ترغب في عزل واحدة محددة. prediction_source معيار الاستفسار مع سلج المصدر المستقر:

# Philadelphia Fed Survey of Professional Forecasters only
curl "https://fxmacrodata.com/api/v1/predictions/usd/inflation?prediction_source=philly_fed_spf"

# ECB Survey of Professional Forecasters (requires API key)
curl "https://fxmacrodata.com/api/v1/predictions/eur/inflation?prediction_source=ecb_spf&api_key=YOUR_API_KEY"

# RBNZ Monetary Policy Statement (requires API key)
curl "https://fxmacrodata.com/api/v1/predictions/nzd/inflation?prediction_source=rbnz_mps&api_key=YOUR_API_KEY"

# IMF World Economic Outlook
curl "https://fxmacrodata.com/api/v1/predictions/usd/inflation?prediction_source=imf_weo"

- ... prediction_source_label يذكر الموقع الإلكتروني للشركة في الموقع الرسمي الخاص بها. prediction_source قذيفة لتحرير و التواصل البرمجي

استخدام جدول الإصدارات للتوقعات القادمة

- ... تقويم الإصدار يظهر تواريخ الإعلان القادمة لجميع العملات المغطاة. عند دمج بيانات التقويم مع نقطة النهاية للتنبؤات، يمكنك إنشاء لوحة تحكم متوقعة تظهر الإجماع الحالي لكل إصدار قادم.

import requests
from datetime import date

API_KEY = "YOUR_API_KEY"
BASE = "https://fxmacrodata.com/api"

# Get upcoming USD releases
calendar = requests.get(f"{BASE}/v1/calendar/usd").json()
upcoming = [row for row in calendar["data"] if row.get("release")]

# For each upcoming release, fetch the current consensus prediction
for release in upcoming[:5]:
    indicator = release["release"]
    preds = requests.get(
        f"{BASE}/v1/predictions/usd/{indicator}",
        params={"prediction_type": "market_consensus"},
        timeout=30,
    ).json()
    if preds.get("data"):
        latest_pred = preds["data"][-1]
        if latest_pred.get("predictions"):
            val = latest_pred["predictions"][0]["predicted_value"]
            print(f"{indicator}: consensus={val}")

ملخص المرجعية للنقطة النهائية

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

تم تصميم API للتنبؤات ليقع بجانب التضخم- لا سعر سعر السياسة، وصفحات لمراجعة المؤشرات الأخرى حيث تكون المقارنات بين العملات مفيدة جدا و تقويم الإصدار، عندما يتوافق توقيت الإعلانات القادمة مع التوقعات التي تسبقها.