Forecasting Macro Releases: How to Use the FXMacroData Predictions API

Pourquoi les prévisions comptent autant que le nombre lui-même

Les marchés des changes ne se déplacent pas sur les données publiées ils se déplacer sur les surprises. Réserve fédérale ou le Banque centrale européenne Si la paire publie de nouvelles données, le marché a déjà formé une attente. si la paires correspondent au consensus, à peine se contracte. si elle dévie, vous obtenez le pic.

Pour travailler avec elle de manière systématique, vous avez besoin d'accéder à la prévision aux côtés de l'observation réelle, reliée entre elles de manière à vous permettre de calculer la surprise sans contaminer vos données avec le point de vue.

L'API de prévisions FXMacroData est conçue pour ce flux de travail. Elle fait surface des prévision de cinq catégories de sources distinctes et relie chaque prédiction à son annonce cible via un système stable. announcement_id, vous pouvez donc combiner les prédictions avec les valeurs réalisées, mesurer la précision des prévisions dans le temps et créer des indices de surprise pour tout indicateur et combinaison de devises qui vous intéressent.

Quels sont les résultats de la prédiction

Deux voies exposent les données de prédiction:

• /api/v1/predictions/{currency} toutes les prévisions pour une devise, pour chaque indicateur du catalogue, avec des filtres optionnels pour l'indicateur, le type de prévision et la source.
• /api/v1/predictions/{currency}/{indicator} toutes les prévisions pour une paire de devises et d'indicateurs spécifiques.

Les deux voies sont gratuites pour les USD. Les devises autres que les USD nécessitent une clé API professionnelle.

Les groupes de réponse sont inscrits par annonce. announcement_id une clé stable et déterministe sous la forme {currency}_{indicator}_{date} suivi d'une predictions La liste de référence est une liste où chaque entrée enregistre la valeur prévue, sa source et une étiquette lisible par l'homme. Inflation en dollars américainsLe texte est le suivant:

{
  "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"
        }
      ]
    }
  ]
}

Le announcement_id sur chaque ligne de prédiction est identique à celle renvoyée par /api/v1/announcements/{currency}/{indicator}, donc une simple combinaison de dictionnaires est tout ce dont vous avez besoin pour associer chaque prévision à son observation réalisée.

Catégories de sources de prévisions

- Il y en a cinq . prediction_type La compréhension de la différence est importante pour la façon dont vous pondérez et interprétez chaque prévision:

Chaque source sert un but d'analyse différent. Le consensus du marché est l'attente du marché à court terme qui stimule la réaction immédiate du devises le jour de la publication. Les prévisions de la banque centrale reflètent les propres perspectives de l'institution et sont utiles pour suivre l'évolution des projections de la Banque entre les réunions.

Construire un index surprise en Python

L'application la plus directe de l'API de prévisions est le calcul d'un indice de surprise de sortie l'écart de l"impression réelle par rapport aux attentes du marché, exprimé en écarts types de surprises historiques. Les effectifs non agricoles des États-UnisLe texte est le suivant:

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

La sortie vous donne une série chronologique de surprises normalisées qui peuvent être directement corrélées avec les mouvements au comptant de l'USD les jours de sortie pour quantifier le coefficient de transmission surprise-FX pour un indicateur donné.

Comparaison des prévisions des banques centrales avec le consensus du marché

Un signal utile dans les paires de devises sensibles au taux est la divergence entre ce que la banque centrale projette et ce que le marché attend. Lorsque les deux convergent, cela indique souvent que le market a complètement digéré les directives de la banques.

Vous pouvez récupérer les deux types de prévisions en une seule demande et calculer la divergence directement:

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']})")

La divergence positive (la banque centrale projette une inflation supérieure à celle du marché) est généralement un signal de faucon. La banque possède soit des informations non publiques, soit elle signale délibérément une tolérance à une infusion supérieure au seuil. calendrier de sortieJe suis désolé .

Comparaison des prévisions entre les devises et les prévistes du FMI

Les projections de la WEO du FMI existent pour chaque devise couverte et utilisent une méthodologie cohérente, elles sont donc bien adaptées aux comparaisons entre devises. Le PIB Les prévisions pour les quatre principales devises liées aux matières premières sont classées par croissance attendue:

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

Ce type de classement s'inscrit naturellement dans les cadres de valeur relative des paires de devises de matières premières comme AUD/CAD ou NZD/AUD, où les différentiels de croissance sont un moteur principal du positionnement à moyen terme.

Filtrage par source de prédiction

Lorsque plusieurs prédictions provenant de sources différentes sont contenues dans une seule annonce, vous voudrez peut-être en isoler une spécifique. prediction_source paramètre de requête avec le slug source stable:

# 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"

Le prediction_source_label Dans le champ de réponse, le nom complet de la source, qui est lisible par l'homme, est indiqué, ce qui convient aux étiquettes des graphiques et aux notes de bas de page des rapports. prediction_source une boulette pour le filtrage et les joints programmatiques.

Utilisation du calendrier de publication pour les prévisions à venir

Le calendrier de sortie Lorsque vous combinez les données du calendrier avec le point final des prédictions, vous pouvez créer un tableau de bord prospectif qui montre le consensus actuel pour chaque version à venir.

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

Résumé de référence des points de départ

La documentation complète des paramètres est disponible sur le site Page de référence APILe tableau ci-dessous donne une référence rapide pour les deux voies de prédiction:

L' API de prédiction est conçue pour s' asseoir à côté du inflationJe suis désolé . taux de réglementation, et autres pages de vue d' ensemble des indicateurs où les comparaisons entre devises sont les plus utiles et les calendrier de sortie, lorsque le calendrier des annonces à venir correspond aux prévisions qui les précèdent.