How To Query Fxmacrodata Via Graphql

No final deste guia, poderá consultar qualquer indicador macroeconómico, descobrir o catálogo completo dos dados disponíveis e verificar as datas de lançamento através do FXMacroData Ponto final do GraphQL usando nada mais do que curlVocê também saberá como agrupar várias consultas em uma única ida e volta para que seus scripts permaneçam magros e rápidos.

Por que GraphQL em vez de REST?

A API REST FXMacroData serve cada indicador em seu próprio ponto final uma ida e volta por combinação de moeda / indicador. GraphQL permite que você declare exatamente os campos que você precisa e combine várias consultas independentes em uma única solicitação HTTP. e a taxa de juro da GBP e O calendário de lançamento próximo para ambas as moedas, ou seja, um POST em vez de quatro pedidos GET.

A superfície do GraphQL espelha os endpoints públicos REST exatamente: as mesmas regras de autenticação, os mesmos dados e os mesmos nomes de campo apenas servido através de um único POST /api/v1/graphql ponto final com um corpo JSON.

Passo 1 Envie sua primeira consulta GraphQL

Cada solicitação GraphQL é um objeto JSON com um query chave cujo valor é a sua cadeia de consulta GraphQL. Comece com uma consulta de inflação gratuita USD sem chave API necessária:

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

A resposta é o GraphQL JSON padrão envolto em um data Envelope:

{
  "data": {
    "announcements": {
      "currency": "USD",
      "indicator": "inflation",
      "data": [
        { "date": "2025-01-01", "val": 3.0, "pctChange": null },
        { "date": "2025-02-01", "val": 2.8, "pctChange": -6.67 },
        { "date": "2025-03-01", "val": 2.4, "pctChange": -14.29 }
      ]
    }
  }
}

Para qualquer moeda que não seja USD, adicione sua chave API como um parâmetro de consulta no endpoint URL:

https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY

Passo 2 Descubra os indicadores disponíveis com dataCatalogue

Antes de consultar um indicador específico, pode perguntar à API quais os dados que tem para qualquer moeda. dataCatalogue A consulta devolve cada caracol de indicador disponível, o seu nome legível pelo homem, unidade, frequência de liberação e se o banco central publica uma previsão oficial para ele.

curl -s -X POST "https://fxmacrodata.com/api/v1/graphql" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ dataCatalogue(currency: \"EUR\") { currency indicators { slug name unit frequency hasOfficialForecast } } }"
  }'

Exemplo de resposta (abreviado):

{
  "data": {
    "dataCatalogue": {
      "currency": "EUR",
      "indicators": [
        { "slug": "inflation",    "name": "Inflation (CPI)", "unit": "%",    "frequency": "monthly",   "hasOfficialForecast": false },
        { "slug": "policy_rate",  "name": "Policy Rate",     "unit": "%",    "frequency": "irregular",  "hasOfficialForecast": true  },
        { "slug": "gdp",          "name": "GDP Growth",      "unit": "%",    "frequency": "quarterly", "hasOfficialForecast": false },
        { "slug": "unemployment", "name": "Unemployment",    "unit": "%",    "frequency": "monthly",   "hasOfficialForecast": false }
      ]
    }
  }
}

O ... slug Os valores são as cordas exatas que você passa como o indicator Argumento em seguida . announcements O catálogo completo dos indicadores pode ser consultado de forma interativa no Documentação de dados da API- Não .

Passo 3 Obter dados históricos com filtros de data opcionais

O ... announcements A consulta aceita opcional startDate E ... endDate Argumentos em YYYY-MM-DD O formato é o seguinte: , e . Sem eles, a API retorna uma janela padrão razoável (normalmente 1224 meses).

curl -s -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { announcements(currency: \"AUD\", indicator: \"policy_rate\", startDate: \"2024-01-01\") { currency indicator hasOfficialForecast cbTarget { description current { effectiveFrom target } } data { date val announcementDatetime } } }"
  }'

Destaques das respostas:

{
  "data": {
    "announcements": {
      "currency": "AUD",
      "indicator": "policy_rate",
      "hasOfficialForecast": true,
      "cbTarget": {
        "description": "RBA cash rate target band",
        "current": { "effectiveFrom": "2023-11-07", "target": 4.35 }
      },
      "data": [
        { "date": "2024-02-06", "val": 4.35, "announcementDatetime": 1707199200 },
        { "date": "2024-03-19", "val": 4.35, "announcementDatetime": 1710813600 }
      ]
    }
  }
}

announcementDatetime é um selo de tempo Unix (segundos, UTC) da publicação oficial. Documentação sobre a política de taxas do AUD- Não .

Passo 4 Consultar o calendário de lançamento

O ... calendar query retorna os horários de anúncio UTC programados para cada lançamento de indicador próximo para uma determinada moeda. indicator O objectivo é reduzir os resultados a um único indicador.

curl -s -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ calendar(currency: \"GBP\", indicator: \"inflation\") { currency data { release announcementDatetime } } }"
  }'

{
  "data": {
    "calendar": {
      "currency": "GBP",
      "data": [
        { "release": "inflation", "announcementDatetime": 1745917200 }
      ]
    }
  }
}

Converta-te . announcementDatetime para uma hora UTC legível por humanos em Python com datetime.utcfromtimestamp(1745917200), ou em JavaScript com new Date(1745917200 * 1000).toISOString()Para obter informações sobre o indicador de inflação da libra esterlina , ver o Docs de inflação GBP- Não .

Passo 5 Batch de várias consultas numa única solicitação

A maior vantagem prática do GraphQL é a capacidade de nomear e enviar várias consultas independentes em um único HTTP POST. Use aliases de consulta para evitar conflitos de nomes de campos cada alias se torna uma chave separada no data Objeto de resposta.

curl -s -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query MultiIndicator { eurInflation: announcements(currency: \"EUR\", indicator: \"inflation\") { currency indicator data { date val } } gbpRate: announcements(currency: \"GBP\", indicator: \"policy_rate\") { currency indicator data { date val } } audCalendar: calendar(currency: \"AUD\") { currency data { release announcementDatetime } } }"
  }'

A resposta leva os três resultados numa carga útil:

{
  "data": {
    "eurInflation": { "currency": "EUR", "indicator": "inflation", "data": [ ... ] },
    "gbpRate":      { "currency": "GBP", "indicator": "policy_rate", "data": [ ... ] },
    "audCalendar":  { "currency": "AUD", "data": [ ... ] }
  }
}

Passo 6 Cliente Python

O padrão abaixo envolve solicitações GraphQL em um pequeno auxiliar para que o código da sua aplicação permaneça legível.

import requests

GRAPHQL_URL = "https://fxmacrodata.com/api/v1/graphql"
API_KEY = "YOUR_API_KEY"   # leave empty for free USD/catalogue endpoints

def gql(query: str) -> dict:
    """Send a GraphQL query and return the parsed `data` object."""
    params = {"api_key": API_KEY} if API_KEY else {}
    resp = requests.post(
        GRAPHQL_URL,
        params=params,
        json={"query": query},
        headers={"Content-Type": "application/json"},
        timeout=15,
    )
    resp.raise_for_status()
    payload = resp.json()
    if "errors" in payload:
        raise RuntimeError(f"GraphQL errors: {payload['errors']}")
    return payload["data"]


# ── Discover indicators for AUD ──────────────────────────────────────────────
catalogue = gql('{ dataCatalogue(currency: "AUD") { indicators { slug name frequency } } }')
for ind in catalogue["dataCatalogue"]["indicators"]:
    print(f"  {ind['slug']:25s}  {ind['name']}  ({ind['frequency']})")

# ── Fetch EUR inflation + GBP policy rate in one round-trip ─────────────────
batch = gql('''
query {
  eurInflation: announcements(currency: "EUR", indicator: "inflation") {
    currency indicator data { date val pctChange }
  }
  gbpRate: announcements(currency: "GBP", indicator: "policy_rate") {
    currency indicator data { date val }
  }
}
''')

eur_latest = batch["eurInflation"]["data"][-1]
gbp_latest = batch["gbpRate"]["data"][-1]
print(f"EUR CPI   {eur_latest['date']}: {eur_latest['val']}%  ({eur_latest['pctChange']:+.2f}% MoM)")
print(f"GBP Rate  {gbp_latest['date']}: {gbp_latest['val']}%")

Passo 7 JavaScript / Node.js cliente

O nativo . fetch API (Node.js 18+) lida com solicitações GraphQL com o mínimo de boilerplate.

const GRAPHQL_URL = "https://fxmacrodata.com/api/v1/graphql";
const API_KEY = "YOUR_API_KEY"; // set to "" for free USD/catalogue endpoints

async function gql(query) {
  const url = API_KEY ? `${GRAPHQL_URL}?api_key=${API_KEY}` : GRAPHQL_URL;
  const resp = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query }),
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const payload = await resp.json();
  if (payload.errors) throw new Error(JSON.stringify(payload.errors));
  return payload.data;
}

// Batched query: EUR inflation + calendar
const data = await gql(`
  query {
    eurInflation: announcements(currency: "EUR", indicator: "inflation") {
      data { date val pctChange }
    }
    eurCalendar: calendar(currency: "EUR", indicator: "inflation") {
      data { release announcementDatetime }
    }
  }
`);

const latest = data.eurInflation.data.at(-1);
const nextRelease = data.eurCalendar.data[0];

console.log(`EUR CPI ${latest.date}: ${latest.val}% (${latest.pctChange > 0 ? "+" : ""}${latest.pctChange?.toFixed(2)}% MoM)`);
if (nextRelease) {
  const dt = new Date(nextRelease.announcementDatetime * 1000).toISOString();
  console.log(`Next EUR inflation release: ${dt}`);
}

Passo 8 Lidar com erros com elegância

GraphQL retorna HTTP 200 mesmo quando um campo de consulta falha. errors Arquivo junto a qualquer parcial data Verifique se há essa matriz antes de usar a resposta um alias falhado em uma consulta batch não impedirá que os outros aliases retornem dados.

payload = resp.json()

# Partial success: some aliases may have data, others may have errors
if "errors" in payload:
    for err in payload["errors"]:
        print(f"[GraphQL error] {err.get('message')} — path: {err.get('path')}")

data = payload.get("data") or {}
if "eurInflation" in data and data["eurInflation"]:
    process(data["eurInflation"])

Próximos passos

Agora que você pode consultar o endpoint GraphQL fluentemente, algumas extensões naturais farão sua integração produção pronta:

• Agende consultas em torno das horas de lançamento. Combina o calendar query com o padrão de programação descrito em Como usar a API do calendário de lançamento para agendar buscas de indicadores Acorda antes de cada anúncio e dispara o teu announcements A consulta é efectuada no momento em que são publicados novos dados.
• Explore o esquema completo de forma interativa. Se você tem acesso a um ambiente de desenvolvimento com ENABLE_GRAPHIQL=true- Abre . /api/v1/graphql no seu navegador para usar o GraphiQL IDE integrado com documentação de preenchimento automático e em linha para cada campo.
• Expanda a sua cobertura para mais moedas. Corram . dataCatalogue para cada uma das moedas suportadas USD, EUR, GBP, AUD, CAD, JPY, CHF e NZD para criar uma imagem completa dos dados disponíveis no universo FX do G8.

A equipa FXMacroData