How To Query Fxmacrodata Via Graphql

Al final de esta guía podrá consultar cualquier indicador macroeconómico, descubrir el catálogo completo de datos disponibles y consultar las próximas fechas de publicación a través de FXMacroData Punto final de GraphQL no usar más que curlTambién sabrá cómo agrupar varias consultas en un solo viaje de ida y vuelta para que sus scripts se mantengan rápidos y rápidos.

¿Por qué GraphQL en lugar de REST?

La API REST de FXMacroData sirve a cada indicador en su propio punto final una ida y vuelta por combinación de moneda / indicador. GraphQL le permite declarar exactamente los campos que necesita y combinar múltiples consultas independientes en una sola solicitud HTTP. Si desea la serie de inflación EUR y el tipo de interés de referencia de la libra esterlina y El calendario de liberación de las dos monedas, es decir, una POST en lugar de cuatro solicitudes GET.

La superficie de GraphQL refleja los puntos finales públicos REST exactamente: las mismas reglas de autenticación, los mismos datos y los mismos nombres de campo sólo se sirve a través de un solo POST /api/v1/graphql punto final con un cuerpo JSON.

Paso 1 Envía tu primera consulta de GraphQL

Cada solicitud de GraphQL es un objeto JSON con un query clave cuyo valor es la cadena de consulta de GraphQL. Comience con una consulta de inflación de USD gratuita sin necesidad de clave API:

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

La respuesta es GraphQL JSON estándar envuelto en un data Envase:

{
  "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 cualquier moneda que no sea USD, añada su clave API como parámetro de consulta en la URL del punto final:

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

Paso 2 Descubra los indicadores disponibles con dataCatalogue

Antes de consultar un indicador específico, puede preguntar a la API qué datos tiene para cualquier moneda. dataCatalogue La consulta devuelve cada caracol de indicador disponible, su nombre legible para el ser humano, su unidad, su frecuencia de publicación y si el banco central publica una previsión oficial para él.

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

Ejemplo de respuesta (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 }
      ]
    }
  }
}

El slug Los valores son las cadenas exactas que se pasan como el indicator - ¿ Qué es lo que quieres decir ? announcements Puede consultar el catálogo completo de indicadores de forma interactiva en el Documento de datos de la API- ¿ Qué ?

Paso 3 Obtener datos históricos con filtros de fecha opcionales

El announcements La consulta acepta opcional startDate ¿ Qué ? endDate ¿Qué es lo que está pasando? YYYY-MM-DD Sin ellos, la API devuelve una ventana predeterminada razonable (normalmente 1224 meses). También puede solicitar el objetivo del banco central junto con la serie útil al comparar la lectura en vivo con el objetivo oficial de la tasa.

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

Respuestas destacadas:

{
  "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 El valor de los indicadores de AUD para el año 2010 es de un tiempo de marca Unix (segundos, UTC) de la publicación oficial. Documentación de las tasas de interés de política del AUD- ¿ Qué ?

Paso 4 Consultar el calendario de lanzamiento

El calendar La consulta devuelve los horarios de anuncio UTC programados para cada próxima publicación de indicadores para una moneda determinada. indicator El argumento para reducir los resultados a un ú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 }
      ]
    }
  }
}

Conviértete . announcementDatetime a una hora UTC legible por el hombre en Python con datetime.utcfromtimestamp(1745917200), o en JavaScript con new Date(1745917200 * 1000).toISOString()Para obtener más detalles sobre el indicador de inflación en GBP , véase el Documentación sobre la inflación de la libra esterlina- ¿ Qué ?

Paso 5 Batch de varias consultas en una sola solicitud

La mayor ventaja práctica de GraphQL es la capacidad de nombrar y enviar varias consultas independientes en un solo POST HTTP. data Objeto de respuesta.

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

La respuesta lleva los tres resultados en una carga útil:

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

Paso 6 Cliente Python

El patrón de abajo envuelve las solicitudes de GraphQL en un pequeño ayudante para que su código de aplicación permanezca legible.

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

Paso 7 JavaScript / cliente Node.js

El nativo . fetch API (Node.js 18+) maneja las solicitudes de GraphQL con un mínimo de tiempo de trabajo.

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}`);
}

Paso 8 Maneje los errores con gracia

GraphQL devuelve HTTP 200 incluso cuando un campo de consulta falla. errors Arranque junto a cualquier parcial data que tuvo éxito. Compruebe esta matriz antes de usar la respuesta un alias fallido en una consulta batch no impedirá que los otros alias devuelvan datos.

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

Los siguientes pasos

Ahora que puede consultar el punto final de GraphQL con fluidez, algunas extensiones naturales harán que su integración esté lista para la producción:

• Programe consultas en torno a las horas de lanzamiento. Combina el calendar Cómo usar la API de calendario de lanzamiento para programar las búsquedas de indicadores despierta justo antes de cada anuncio y dispara tu announcements En el caso de los datos de la UE, la consulta se realiza en el momento en que se publican nuevos datos.
• Explora el esquema completo de forma interactiva. Si tiene acceso a un entorno de desarrollo con ENABLE_GRAPHIQL=true- ¿ Qué ? /api/v1/graphql en su navegador para utilizar el IDE GraphiQL incorporado con documentación automática y en línea para cada campo.
• Extienda su cobertura a más monedas. ¡ Corren ! dataCatalogue para cada una de las monedas soportadas USD, EUR, GBP, AUD, CAD, JPY, CHF y NZD para obtener una imagen completa de los datos disponibles en el universo FX del G8.

El equipo de FXMacroData