Forecasting Macro Releases: How to Use the FXMacroData Predictions API

Por que as previsões são tão importantes quanto o número em si

Os mercados de divisas não se movem em função de publicações de dados movem-se em funcção de surpresas. Reserva Federal ou o Banco Central Europeu Se o valor da moeda for igual ao valor do mercado, o par não se moverá muito, mas se ele se desviar, você terá um pico.

Para trabalhar com ele sistematicamente, você precisa acessar a previsão ao lado da observação real, ligada de forma a permitir que você calcule a surpresa sem contaminar seus dados com o lookahead.

A API de previsões FXMacroData foi construída para este fluxo de trabalho. announcement_id, para que possa juntar previsões com valores realizados, medir a precisão das previsões ao longo do tempo e construir índices surpresa para qualquer indicador e combinação de moedas que lhe interesse.

O que o ponto final das previsões retorna

Duas rotas expõem dados de previsão:

• /api/v1/predictions/{currency} todas as previsões para uma moeda, em todos os indicadores do catálogo, com filtros opcionais para indicador, tipo de previsão e fonte.
• /api/v1/predictions/{currency}/{indicator} todas as previsões para um par de moedas e indicadores específicos.

Ambas as rotas são gratuitas para USD. As moedas não USD exigem uma chave API profissional.

Os grupos de resposta são inscritos por anúncio. announcement_id uma chave estável e determinista na forma {currency}_{indicator}_{date} seguido de predictions Lista onde cada entrada regista o valor previsto, a sua fonte e um rótulo legível pelo homem. Inflação em USD- Não .

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

O ... announcement_id em cada linha de previsão é idêntica à que é devolvida por /api/v1/announcements/{currency}/{indicator}, por isso uma simples ligação de dicionário é tudo o que você precisa para emparelhar cada previsão com a sua observação realizada.

Categorias de fontes de previsão

Cinco . prediction_type A compreensão da diferença é importante para a forma como ponderamos e interpretamos cada previsão:

Cada fonte serve a um propósito analítico diferente. O consenso do mercado é a expectativa do mercado de curto horizonte que impulsiona a reação imediata de câmbio no dia do lançamento. As previsões do banco central refletem a própria perspectiva da instituição e são úteis para rastrear o quanto as projeções do banco evoluem entre as reuniões. As projeções da WEO do FMI fornecem uma linha de base neutra de vários anos e são consistentes em todas as 18 moedas cobertas, tornando-as úteas para comparações entre moedas.

Construindo um índice surpresa em Python

A aplicação mais direta da API de previsões é calcular um índice de surpresa de lançamento o desvio da impressão real da expectativa do mercado, expresso em desvios padrão de surpresas históricas. Empregados não agrícolas dos EUA- Não .

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

A saída fornece uma série temporal de surpresas normalizadas que podem ser diretamente correlacionadas com os movimentos spot do USD nos dias de lançamento para quantificar o coeficiente de transmissão surpresa-FX para qualquer indicador.

Comparação das previsões do banco central com o consenso do mercado

O mercado de moeda de câmbio é um dos principais mercados de câmbios de câmpio de câmbia de câmpios de câmbero de câmvio de câmpia de câmrio de câmbria.

Pode recuperar ambos os tipos de previsão numa única solicitação e calcular a divergência 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']})")

A diferença positiva (o banco central projeta uma inflação mais elevada do que o mercado) é tipicamente um sinal de falcão. O banco ou tem informações não públicas ou está deliberadamente sinalizando tolerância para inflação acima da meta. Calendário de lançamento- Não .

Comparação das previsões entre moedas com o WEO do FMI

Como existem projecções do WEO do FMI para cada moeda coberta e utilizam uma metodologia consistente, elas são bem adequadas para comparações entre moedas. PIB As previsões para as quatro principais moedas ligadas a matérias-primas são classificadas por crescimento 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 classificação alimenta-se naturalmente em quadros de valor relativo para pares de moeda de commodities como AUD/CAD ou NZD/AUD, onde os diferenciais de crescimento são um dos principais impulsionadores do posicionamento de porte a médio prazo.

Filtragem por fonte de previsão

Quando um único anúncio tem várias previsões de diferentes fontes, você pode querer isolar uma específica. prediction_source Parâmetro de consulta com a barra de origem estável:

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

O ... prediction_source_label O campo na resposta indica o nome completo da fonte, legível para o ser humano, adequado para rótulos de gráficos e notas de rodapé de relatórios. prediction_source Bala para filtragem e juntas programáticas.

Utilização do calendário de publicação para previsões futuras

O ... Calendário de lançamento Quando você combina dados de calendário com o ponto final de previsão, você pode criar um painel prospectivo que mostra o consenso atual para cada versão 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}")

Resumo de referência do ponto final

A documentação completa dos parâmetros está disponível no Página de referência da APIA tabela abaixo dá uma rápida referência para as duas rotas de previsão:

A API de previsões foi projetada para se sentar ao lado do inflação- Não . Taxa de política, e outras páginas de síntese de indicadores onde as comparações entre moedas são mais úteis e o Calendário de lançamento, quando o calendário dos próximos anúncios atender às previsões que os precedem.