How To Query Fxmacrodata Via Graphql

À la fin de ce guide, vous pourrez consulter n'importe quel indicateur macroéconomique, découvrir le catalogue complet des données disponibles et vérifier les dates de sortie à venir à travers le FXMacroData Point final de GraphQL ne pas utiliser plus que curlVous saurez également comment regrouper plusieurs requêtes en un seul aller-retour afin que vos scripts restent maigres et rapides.

Pourquoi GraphQL au lieu de REST ?

L'API REST FXMacroData sert chaque indicateur à son propre point final un aller-retour par combinaison de devises/indicateurs. GraphQL vous permet de déclarer exactement les champs dont vous avez besoin et de combiner plusieurs requêtes indépendantes en une seule demande HTTP. Si vous voulez la série d'inflation EUR et le taux directeur de la livre sterling et Le calendrier de sortie à venir pour les deux monnaies, c'est-à-dire une POST au lieu de quatre demandes GET.

La surface GraphQL reflète exactement les terminaux publics REST: les mêmes règles d'authentification, les mêmes données et les mêmes noms de champ simplement servis par un seul POST /api/v1/graphql point final avec un corps JSON.

Étape 1 Envoyez votre première requête GraphQL

Chaque requête GraphQL est un objet JSON avec un query clé dont la valeur est votre chaîne de requête GraphQL. Commencez avec une requête d'inflation gratuite USD aucune clé API requise:

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 réponse est un GraphQL JSON standard enveloppé dans un data Enveloppe:

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

Pour toute devise autre que l'USD, ajoutez votre clé API comme paramètre de requête à l'URL du point de terminaison:

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

Étape 2 Découvrez les indicateurs disponibles avec dataCatalogue

Avant de consulter un indicateur spécifique, vous pouvez demander à l'API quelles données elle a pour n'importe quelle devise. dataCatalogue La requête renvoie chaque slug d'indicateur disponible, son nom lisible par l'homme, son unité, sa fréquence de publication et si la banque centrale publie une prévision officielle pour celui-ci.

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

Exemple de réponse (abrégée):

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

Le slug Les valeurs sont les chaînes exactes que vous passez comme le indicator Je vous en parlerai plus tard . announcements Vous pouvez consulter le catalogue complet des indicateurs de manière interactive à l'adresse suivante: Les données de l'APIJe suis désolé .

Étape 3 Retrouvez les données historiques avec des filtres de date optionnels

Le announcements La requête accepte optionnellement . startDate Je suis désolé . endDate Les arguments dans YYYY-MM-DD L'API retourne une fenêtre par défaut raisonnable (généralement 1224 mois). Vous pouvez également demander l'objectif de la banque centrale aux côtés de la série utile pour comparer la lecture en direct avec l'objet du taux officiel.

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

Les points forts des réponses:

{
  "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 est un horodatage Unix (secondes, UTC) de la publication officielle. Documents relatifs aux taux directeurs de l'AUDJe suis désolé .

Étape 4 Rechercher le calendrier de sortie

Le calendar La requête renvoie les heures d'annonce UTC prévues pour chaque prochaine sortie d'indicateur pour une devise donnée. indicator L'argument est de réduire les résultats à un seul indicateur.

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

Convertissez-vous . announcementDatetime à une heure UTC lisible par l'homme en Python avec datetime.utcfromtimestamp(1745917200), ou en JavaScript avec new Date(1745917200 * 1000).toISOString()Pour plus de détails sur l' indicateur d' inflation en GBP , voir le tableau ci-dessous . Les données sur l'inflation en GBPJe suis désolé .

Étape 5 Batch plusieurs requêtes dans une seule demande

Le plus grand avantage pratique de GraphQL est la capacité de nommer et d'envoyer plusieurs requêtes indépendantes dans un seul HTTP POST. Utilisez des alias de requête pour éviter les conflits de noms de champ chaque alias devient une clé séparée dans le data objet de réponse.

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 réponse comporte les trois résultats dans une seule charge utile:

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

Étape 6 Client Python

Le modèle ci-dessous enveloppe les requêtes GraphQL dans un petit assistant afin que votre code d'application reste lisible. Il prend en charge les requête-singles et les requests-alias par lots avec la même fonction.

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

Étape 7 JavaScript / client Node.js

Le natif . fetch L'API (Node.js 18+) gère les requêtes GraphQL avec un minimum de temps de chargement.

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

8e étape Gérer les erreurs avec élégance

GraphQL renvoie HTTP 200 même lorsqu'un champ de requête échoue. errors - Je ne sais pas . data vérifier si ce tableau est valide avant d'utiliser la réponse un alias raté dans une requête par lots n'empêchera pas les autres alias de renvoyer des données.

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

Les prochaines étapes

Maintenant que vous pouvez interroger le point final GraphQL avec fluidité, quelques extensions naturelles rendront votre intégration prête pour la production:

• Planifiez les requêtes autour des heures de sortie. Combinez les calendar La requête est effectuée avec le schéma de planification décrit dans Comment utiliser l' API du calendrier de sortie pour planifier les récupérations d'indicateurs se réveiller juste avant chaque annonce et tirer votre announcements La requête est effectuée dès la publication de nouvelles données.
• Explorez le schéma complet de façon interactive. Si vous avez accès à un environnement de développement avec ENABLE_GRAPHIQL=true- Je suis désolé . /api/v1/graphql dans votre navigateur pour utiliser l'IDE GraphiQL intégré avec la documentation de remplissage automatique et en ligne pour chaque champ.
• Étendre votre couverture à plus de devises. - Je ne sais pas . dataCatalogue pour chacune des monnaies prises en charge USD, EUR, GBP, AUD, CAD, JPY, CHF et NZD afin de se faire une idée complète des données disponibles dans l'univers des devises du G8.

L'équipe FXMacroData