Forecasting Macro Releases: How to Use the FXMacroData Predictions API

Por qué las previsiones son tan importantes como el número en sí

Los mercados de divisas no se mueven con base en las publicaciones de datos, sino que se muevan con base Reserva Federal o el Banco Central Europeo Si el mercado publica nuevos datos, el mercado ya ha formado una expectativa. si la impresión coincide con el consenso, el par apenas se contrae. si se desvía, obtienes el pico.

Para trabajar con él de manera sistemática, necesita acceso al pronóstico junto con la observación real, vinculado entre sí de una manera que le permita calcular la sorpresa sin contaminar sus datos con lookhead.

La API de predicciones de FXMacroData está construida para este flujo de trabajo. announcement_id, para que pueda unir las predicciones con los valores realizados, medir la precisión del pronóstico a lo largo del tiempo, y construir índices de sorpresa para cualquier indicador y combinación de divisas que le interese.

Lo que devuelve el punto final de las predicciones

Dos rutas exponen los datos de predicción:

• /api/v1/predictions/{currency} todas las previsiones para una moneda, en todos los indicadores del catálogo, con filtros opcionales para indicadores, tipo de predicción y fuente.
• /api/v1/predictions/{currency}/{indicator} todas las previsiones para un par de divisas e indicadores específicos.

Ambas rutas son gratuitas para USD. Las monedas que no son USD requieren una clave API profesional.

Los grupos de respuesta se inscriben mediante anuncio. announcement_id una clave estable y determinista en la forma {currency}_{indicator}_{date} seguido de predictions En la lista de datos se incluye el valor de las previsiones, su fuente y una etiqueta legible para el ser humano. Inflación en dólaresEl artículo 2

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

El announcement_id en cada fila de predicción es idéntica a la devuelta por /api/v1/announcements/{currency}/{indicator}, por lo que una simple unión de diccionario es todo lo que necesita para emparejar cada pronóstico con su observación realizada.

Categorías de fuentes de predicción

- ¿ Qué ? prediction_type La comprensión de la diferencia es importante para la forma en que se evalúa e interpreta cada pronóstico:

Cada fuente sirve a un propósito analítico diferente. El consenso del mercado es la expectativa del mercado de corto horizonte que impulsa la reacción cambiaria inmediata el día de la publicación. Los pronósticos del banco central reflejan las propias perspectivas de la institución y son útiles para rastrear cuánto evolucionan las proyecciones del banco entre reuniones. Los pronosticos del WEO del FMI proporcionan una línea de base neutral de varios años y son consistentes en todas las 18 monedas cubiertas, lo que los hace útiles en comparaciones entre monedas.

Construyendo un índice sorpresa en Python

La aplicación más directa de las predicciones API es el cálculo de un índice de sorpresa de liberación la desviación de la impresión real de la expectativa del mercado, expresada en desviaciones estándar de las sorpresas históricas. Pago de los trabajadores no agrícolas de los Estados UnidosEl artículo 2

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 salida le proporciona una serie temporal de sorpresas normalizadas que pueden correlacionarse directamente con los movimientos al contado del USD en los días de lanzamiento para cuantificar el coeficiente de transmisión de sorpresa a FX para cualquier indicador dado.

Comparación de las previsiones de los bancos centrales con el consenso del mercado

Una señal útil en los pares de divisas sensibles a la tasa es la divergencia entre lo que el banco central proyecta y lo que espera el mercado. Cuando los dos convergen, a menudo indica que el mercado ha digerido completamente la orientación del banco. Cuando divergen, puede indicar una brecha de credibilidad o una verdadera asimetría de información entre el banco y el lado de compra.

Puede recuperar ambos tipos de pronóstico en una sola solicitud y calcular la divergencia directamente:

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 diferencia positiva (el banco central proyecta una inflación más alta que el mercado) es típicamente una señal de halcón. El banco tiene información no pública o está señalando deliberadamente tolerancia para la inflación por encima del objetivo. calendario de liberación- ¿ Qué ?

Comparación de las previsiones entre divisas con el WEO del FMI

Debido a que existen proyecciones de la OEM del FMI para cada moneda cubierta y utilizan una metodología coherente, son adecuadas para las comparaciones entre monedas. El PIB las previsiones de las cuatro principales monedas vinculadas a materias primas y las clasifica según el crecimiento esperado:

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

Este tipo de clasificación se alimenta naturalmente de los marcos de valor relativo de los pares de divisas de materias primas como AUD/CAD o NZD/AUD, donde los diferenciales de crecimiento son un motor principal del posicionamiento de porte a medio plazo.

Filtración por fuente de predicción

Cuando un anuncio tiene múltiples predicciones de diferentes fuentes, es posible que desee aislar una específica. prediction_source Parámetro de consulta con la babosa de origen estable:

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

El prediction_source_label En el campo de respuesta se indica el nombre completo de la fuente, legible para el usuario, adecuado para etiquetas de gráficos y notas al pie de página de informes. prediction_source Chalava para filtrar y juntas programáticas.

Usando el calendario de publicación para las previsiones futuras

El calendario de liberación Cuando se combinan los datos del calendario con el punto final de las predicciones, se puede construir un panel de control prospectivo que muestra el consenso actual para cada versión próxima.

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

Resumen de referencia de los puntos finales

La documentación completa de los parámetros está disponible en el Página de referencia de la APILa tabla siguiente ofrece una rápida referencia para las dos rutas de predicción:

La API de predicciones está diseñada para sentarse junto a la la inflación¿ Qué ? tipo de interés, y otras páginas de descripción general de los indicadores donde las comparaciones entre monedas son más útiles y la calendario de liberación, cuando el momento de los próximos anuncios cumple con las previsiones que los preceden.