Como usar todos os endpoints da API FXMacroData: um guia completo

No final deste guia, você terá exemplos de trabalho para cada ponto final público na FXMacroData API desde a série de anúncios e o calendário de lançamento até o posicionamento COT, preços de metais preciosos, taxas de câmbio e a interface GraphQL para que você possa escolher a ferramenta certa para qualquer fluxo de trabalho de dados macro.

Fase 1 Anúncios: séries de indicadores históricos

O ponto final de anúncios é o núcleo do FXMacroData. Retorna uma série de tempo normalizada e timestampada para qualquer indicador macroeconômico suportado. Cada linha contém a data de observação, o valor liberado e o timestamping exato do Unix da publicação oficial , dando-lhe precisão de segundo nível para pesquisa e backtesting baseados em eventos.

As solicitações USD funcionam sem uma chave API. Para qualquer outra moeda, adicione sua chave como um parâmetro de consulta. Use start_date E ... end_date (AAAA-MM-DD) para reduzir a janela; o padrão é os últimos 365 dias.

# USD inflation series — no key needed
curl "https://fxmacrodata.com/api/v1/announcements/usd/inflation"

# AUD policy rate — Pro key required
curl "https://fxmacrodata.com/api/v1/announcements/aud/policy_rate?api_key=YOUR_API_KEY"

# EUR GDP with a custom date range
curl "https://fxmacrodata.com/api/v1/announcements/eur/gdp?start_date=2024-01-01&end_date=2026-03-01&api_key=YOUR_API_KEY"

{
  "currency": "USD",
  "indicator": "inflation",
  "has_official_forecast": false,
  "start_date": "2025-03-01",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-02-01",
      "val": 2.8,
      "announcement_datetime": 1741082400,
      "pct_change": -0.5,
      "pct_change_12m": -6.7
    }
  ]
}

O ... announcement_datetime field is a Unix timestamp (seconds, UTC) for the exact moment the data was officially published. Use it for event study alignment and to avoid look-ahead bias in backtests. Browse available indicator slugs for any currency with the data catalogue (Step 3) or at Documentação de dados da API- Não .

Passo 2 Calendário de lançamento: prazos de anúncio próximos

O ponto final do calendário retorna os carimbos de tempo de anúncio UTC programados para cada lançamento macro próximo para uma determinada moeda. Use-o para agendar uma busca direcionada que dispara quando novos dados são publicados em vez de pesquisar continuamente em um intervalo fixo.

Não é necessária nenhuma chave API. Filtrar para um indicador específico com o opcional indicator Parâmetro de consulta. Código da moeda especial COMM Retorna o cronograma de liberação da mercadoria.

# All upcoming releases for USD
curl "https://fxmacrodata.com/api/v1/calendar/usd"

# Filter to a single indicator
curl "https://fxmacrodata.com/api/v1/calendar/usd?indicator=non_farm_payrolls"

# Commodity release schedule
curl "https://fxmacrodata.com/api/v1/calendar/COMM"

{
  "currency": "USD",
  "indicator": "non_farm_payrolls",
  "data": [
    {
      "release": "non_farm_payrolls",
      "announcement_datetime": 1746540600,
      "requires_api_key": false
    }
  ]
}

Converte o carimbo de hora para uma hora UTC legível por humanos com datetime.fromtimestamp(ts, tz=timezone.utc) Em Python ou new Date(ts * 1000).toISOString() Para um padrão completo de programação, veja Como usar a API do calendário de lançamento para agendar as buscas de indicadores- Não .

Passo 3 Catálogo de dados: descobrir os indicadores disponíveis

Antes de escrever um código que visa um indicador específico, consulte o catálogo para confirmar o que está disponível para uma moeda. A resposta mapeia cada caracol de indicador para o seu nome legível pelo ser humano, unidade, frequência de liberação e se o banco central publica uma previsão oficial para ele.

# List all indicators for EUR — no key required
curl "https://fxmacrodata.com/api/v1/data_catalogue/eur"

# Include routing and auth discovery metadata per indicator
curl "https://fxmacrodata.com/api/v1/data_catalogue/usd?include_capabilities=true"

{
  "gdp": {
    "name": "GDP Growth",
    "unit": "%QoQ",
    "frequency": "Quarterly",
    "has_official_forecast": false
  },
  "inflation": {
    "name": "Inflation (CPI)",
    "unit": "%YoY",
    "frequency": "Monthly",
    "has_official_forecast": false
  },
  "policy_rate": {
    "name": "Policy Rate",
    "unit": "%",
    "frequency": "Meeting",
    "has_official_forecast": true
  }
}

As chaves de nível superior na resposta são as mesmas . {indicator} As moedas suportadas incluem USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD, CNY, SGD, SEK, DKK, PLN e BRL. Pass include_coverage=true para obter uma grade de disponibilidade de moedas cruzadas em uma única resposta.

Etapa 4 Posicionamento COT: dados especulativos de futuros

O ponto final Commitment of Traders fornece dados semanais de posicionamento da CFTC para contratos futuros de câmbio. Mostra a divisão total do interesse aberto entre participantes não comerciais (especulativos), comerciais (hedger) e não declaráveis um indicador líder amplamente rastreado para inversões de tendência cambial e posicionamentos lotados.

Moedas suportadas: USD, EUR, GBP, JPY, AUD, CAD, CHF, NZD. O USD é gratuito; todas as outras exigem uma chave Pro.

# USD COT history — free
curl "https://fxmacrodata.com/api/v1/cot/usd"

# EUR COT with a custom date range
curl "https://fxmacrodata.com/api/v1/cot/eur?start_date=2025-01-01&api_key=YOUR_API_KEY"

{
  "currency": "EUR",
  "instrument": "EURO FX - CHICAGO MERCANTILE EXCHANGE",
  "fx_overlay": { "pair": "EUR/USD" },
  "start_date": "2025-01-07",
  "end_date": "2026-03-25",
  "data": [
    {
      "date": "2026-03-18",
      "announcement_datetime": 1742493000,
      "open_interest": 812345,
      "noncommercial_long": 185000,
      "noncommercial_short": 92000,
      "noncommercial_net": 93000,
      "commercial_long": 203000,
      "commercial_short": 310000,
      "commercial_net": -107000,
      "nonreportable_long": 21000,
      "nonreportable_short": 9000
    }
  ]
}

O ... noncommercial_net O índice de posicionamento mais frequentemente citado para os traders de FX é o campo (long minus short especulativo). announcement_datetime for the Friday 3:30 PM ET CFTC publication. For EUR pair context see the Docs de taxas de juro de política monetária- Não .

Etapa 5 Metais: preços do ouro, prata e platina

O endpoint de metais retorna séries diárias de preços de metais preciosos provenientes da Royal Mint (fixes da LBMA). Estas séries são úteis como entradas macro entre ativos, especialmente para rastrear fluxos de refúgio seguro e dinâmica vinculada ao USD.

Uma chave API profissional é sempre necessária para este ponto final. gold- Não . silver- Não . platinum- Não .

# Gold LBMA PM Fix daily prices
curl "https://fxmacrodata.com/api/v1/commodities/gold?api_key=YOUR_API_KEY"

# Silver with a date range
curl "https://fxmacrodata.com/api/v1/commodities/silver?start_date=2025-01-01&api_key=YOUR_API_KEY"

# Platinum spot
curl "https://fxmacrodata.com/api/v1/commodities/platinum?api_key=YOUR_API_KEY"

{
  "currency": "COMM",
  "indicator": "gold",
  "has_official_forecast": false,
  "start_date": "2025-03-30",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-03-28",
      "val": 2870.00,
      "pct_change": 1.2,
      "pct_change_12m": 30.1
    }
  ]
}

A forma da resposta é idêntica ao ponto final dos anúncios, para que você possa reutilizar o mesmo código de análise. announcement_datetime É ... null para séries de preços diárias e é preenchido apenas para eventos oficiais de publicação mensal.

Etapa 6 Taxas de câmbio: séries de preços spot diárias

O endpoint forex retorna dados diários de taxa de spot OHLC para qualquer par de moedas suportado. Não é necessária chave API. Use-o para alinhar as versões do indicador macro com a taxa de câmbio contemporânea para backtesting ou fluxos de trabalho de visualização de gráficos.

Base de passagem e citação como segmentos de caminho separados (por exemplo /forex/eur/usd para o EUR/USD). indicators Parâmetro de consulta.

# EUR/USD daily rates — no key required
curl "https://fxmacrodata.com/api/v1/forex/eur/usd"

# AUD/JPY with a custom date range
curl "https://fxmacrodata.com/api/v1/forex/aud/jpy?start_date=2025-01-01"

# GBP/USD with technical indicators overlaid
curl "https://fxmacrodata.com/api/v1/forex/gbp/usd?indicators=sma_20,rsi_14"

{
  "base": "EUR",
  "quote": "USD",
  "start_date": "2025-03-30",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-03-28",
      "close": 1.0832,
      "open": 1.0821,
      "high": 1.0867,
      "low": 1.0798
    }
  ]
}

Etapa 7 Sessões de mercado: estado da sessão em tempo real

O endpoint das sessões de mercado retorna o status atual de abertura/fechamento para as quatro principais sessões FX Sydney, Tóquio, Londres e Nova York , juntamente com as janelas de sobreposição ativa. Não é necessária nenhuma chave API. Use-o para gatear a automação sensível ao tempo para janelas com pico de liquidez ou para anotar gráficos com limites de sessão.

# Real-time snapshot — no key required
curl "https://fxmacrodata.com/api/v1/market_sessions"

# Historical snapshot for scheduling or testing
curl "https://fxmacrodata.com/api/v1/market_sessions?at=2026-03-28T12:00:00Z"

{
  "now_utc": "2026-03-30T08:47:00Z",
  "now_unix": 1743324420,
  "is_market_day": true,
  "sessions": [
    {
      "name": "London",
      "is_open": true,
      "seconds_to_close": 25200,
      "currencies": ["EUR", "GBP", "CHF"],
      "open_utc": "2026-03-30T07:00:00Z",
      "close_utc": "2026-03-30T15:00:00Z"
    }
  ],
  "overlaps": [
    {
      "name": "London / New York",
      "is_active": false,
      "priority": "high",
      "start_utc": "2026-03-30T12:00:00Z",
      "end_utc": "2026-03-30T16:00:00Z",
      "notable_pairs": ["EUR/USD", "GBP/USD", "USD/CHF"],
      "duration_hours": 4
    }
  ]
}

A sobreposição Londres/Nova Iorque é a janela de maior liquidez do dia de negociação e é quando as macros liberam com mais frequência os maiores movimentos spot. is_market_day: false para ignorar a automação nos fins de semana e nos principais feriados de mercado.

Passo 8 GraphQL: batch de várias consultas em uma única solicitação

FXMacroData expõe um endpoint GraphQL que espelha a superfície REST exatamente as mesmas regras de autenticação, os mesmos nomes de campo, os próprios dados mas permite declarar apenas os campos que você precisa e combinar várias consultas em uma única ida e volta HTTP. e Taxa de juro da GBP e um calendário de lançamento AUD, que é um POST em vez de três GETs.

Envia um POST Para ... https://fxmacrodata.com/api/v1/graphql com um corpo JSON contendo um query A chave de código e sua chave de API como um parâmetro de consulta de URL. Os campos raiz disponíveis são announcements- Não . dataCatalogueE ... calendar- Não .

# Single free USD query — no key required
curl -s -X POST "https://fxmacrodata.com/api/v1/graphql" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ announcements(currency: \"USD\", indicator: \"inflation\") { currency indicator data { date val pctChange } } }"
  }'

# Batched: EUR inflation + GBP policy rate in one request
curl -s -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { eurCPI: announcements(currency: \"EUR\", indicator: \"inflation\") { data { date val } } gbpRate: announcements(currency: \"GBP\", indicator: \"policy_rate\") { data { date val } } }"
  }'

{
  "data": {
    "eurCPI":  { "data": [{ "date": "2026-02-28", "val": 2.3 }] },
    "gbpRate": { "data": [{ "date": "2026-03-20", "val": 4.5 }] }
  }
}

GraphQL retorna HTTP 200 mesmo quando um campo de consulta falha erros aparecem em um nível superior errors Para uma implementação completa de Python e JavaScript com manejo de erros e padrões de batching, veja Como consultar FXMacroData através do GraphQL- Não .

Passo 10 Fluxo de trabalho de ponta a ponta do Python

O trecho abaixo reúne os padrões mais comuns em sequência: descubra indicadores disponíveis, verifique o próximo lançamento programado, obtenha duas séries de indicadores em uma única solicitação GraphQL e, em seguida, verifie condicionalmente o estado da sessão de mercado antes de rotear a saída.

import requests
from datetime import datetime, timezone

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


def params(require_key: bool = True) -> dict:
    return {"api_key": API_KEY} if require_key else {}


# 1. Discover available indicators for AUD (free)
catalogue = requests.get(f"{BASE}/data_catalogue/aud", params=params(False), timeout=10)
catalogue.raise_for_status()
print("AUD indicators:", list(catalogue.json().keys())[:5])

# 2. Check the next USD non-farm payrolls release timestamp (free)
cal = requests.get(f"{BASE}/calendar/usd", params={"indicator": "non_farm_payrolls"}, timeout=10)
cal.raise_for_status()
events = cal.json().get("data", [])
if events:
    ts = events[0]["announcement_datetime"]
    dt = datetime.fromtimestamp(ts, tz=timezone.utc)
    print(f"Next NFP release: {dt.strftime('%Y-%m-%d %H:%M UTC')}")

# 3. Fetch EUR inflation + AUD policy rate in one GraphQL request (Pro key)
gql_query = """
query {
  eurCPI: announcements(currency: "EUR", indicator: "inflation") {
    data { date val pctChange }
  }
  audRate: announcements(currency: "AUD", indicator: "policy_rate") {
    data { date val }
  }
}
"""
resp = requests.post(
    f"{BASE}/graphql",
    params={"api_key": API_KEY},
    json={"query": gql_query},
    timeout=15,
)
resp.raise_for_status()
payload = resp.json()
if "errors" in payload:
    raise RuntimeError(payload["errors"])
data = payload["data"]

eur_latest = data["eurCPI"]["data"][-1]
aud_latest = data["audRate"]["data"][-1]
print(f"EUR CPI  {eur_latest['date']}: {eur_latest['val']}%")
print(f"AUD Rate {aud_latest['date']}: {aud_latest['val']}%")

# 4. Check market sessions before triggering a trade alert (free)
sessions_resp = requests.get(f"{BASE}/market_sessions", timeout=10)
sessions_resp.raise_for_status()
session_data = sessions_resp.json()

if session_data["is_market_day"]:
    for overlap in session_data.get("overlaps", []):
        if overlap["is_active"] and overlap["priority"] == "high":
            print(f"High-liquidity window active: {overlap['name']}")
else:
    print("Market closed — skipping alert")

O que pode construir a seguir

Agora você tem exemplos de trabalho para cada ponto final público na FXMacroData API.

• Substitua chamadas REST sequenciais por batching GraphQL. Onde quer que você faça três ou mais solicitações independentes GET, um único GraphQL POST pode substituí-los. Como consultar FXMacroData através do GraphQL- Não .
• Posicionamento COT de camada sobre diferenciais de taxa. Combinar a rede especulativa do ponto final COT com a série de taxas de juro para construir um sinal macro composto em todo o universo monetário do G8.
• Alinhar os preços dos metais com as libertações de moeda. Emparelhe o ouro do ponto final dos metais com a série de anúncios do AUD ou USD para rastrear as correlações de refúgio seguro e dólar ao longo do tempo.

A equipa FXMacroData