Cara Query FXMacroData melalui GraphQL

Pada akhir panduan ini Anda akan dapat menanyakan indikator makroekonomi apa pun, menemukan katalog lengkap data yang tersedia, dan memeriksa tanggal rilis mendatang melalui FXMacroData Titik akhir GraphQL menggunakan tidak lebih dari curlAnda juga akan tahu bagaimana untuk batch beberapa kueri ke dalam satu perjalanan pulang pergi sehingga skrip Anda tetap ramping dan cepat.

Mengapa GraphQL bukan REST?

FXMacroData REST API melayani setiap indikator di titik akhir sendiri satu perjalanan pulang-per kombinasi mata uang / indikator. GraphQL memungkinkan Anda untuk menyatakan persis bidang yang Anda butuhkan dan menggabungkan beberapa kueri independen ke dalam satu permintaan HTTP. Jika Anda ingin seri inflasi EUR dan suku bunga kebijakan GBP dan Kalender rilis mendatang untuk kedua mata uang, yaitu satu POST bukan empat permintaan GET.

Permukaan GraphQL mencerminkan titik akhir REST publik dengan tepat: aturan otentikasi yang sama, data yang sama dan nama lapangan yang sama hanya dilayani melalui satu POST /api/v1/graphql titik akhir dengan tubuh JSON.

Langkah 1 Kirim query GraphQL pertama Anda

Setiap permintaan GraphQL adalah objek JSON dengan query key yang nilainya adalah string query GraphQL Anda. Mulai dengan query inflasi USD gratis tidak diperlukan kunci 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 } } }"
  }'

Tanggapan adalah standar GraphQL JSON dibungkus dalam 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 }
      ]
    }
  }
}

Untuk mata uang non-USD, tambahkan kunci API Anda sebagai parameter kueri pada URL titik akhir:

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

Langkah 2 Temukan indikator yang tersedia dengan dataCatalogue

Sebelum menanyakan indikator tertentu, Anda dapat meminta API untuk mengetahui data apa yang dimiliki untuk mata uang apa pun. dataCatalogue query mengembalikan setiap slug indikator yang tersedia, nama yang dapat dibaca manusia, unit, frekuensi rilis, dan apakah bank sentral menerbitkan perkiraan resmi untuk itu.

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

Contoh jawaban (disingkat):

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

- Apa? slug nilai adalah string yang tepat yang Anda lewatkan sebagai indicator argumentasi di kemudian hari announcements Anda dapat menelusuri katalog indikator secara interaktif di Dokumen data API.

Langkah 3 Mengambil data historis dengan filter tanggal opsional

- Apa? announcements pertanyaan menerima opsional startDate Dan endDate argumen di YYYY-MM-DD format. Without them the API returns a sensible default window (typically 12–24 months). You can also request the central bank target alongside the series — useful when comparing the live reading against the official rate target.

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

Sorotan dari tanggapan:

{
  "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 adalah timestamp Unix (detik, UTC) dari publikasi resmi. Dokumen kebijakan suku bunga AUD.

Langkah 4 Mencari kalender rilis

- Apa? calendar query mengembalikan waktu pengumuman UTC yang dijadwalkan untuk setiap rilis indikator mendatang untuk mata uang tertentu. indicator argumentasi untuk mempersempit hasil ke satu indikator.

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

Berubah announcementDatetime ke waktu UTC yang dapat dibaca manusia di Python dengan datetime.utcfromtimestamp(1745917200), atau dalam JavaScript dengan new Date(1745917200 * 1000).toISOString()Untuk rincian indikator inflasi GBP lihat Docs inflasi GBP.

Langkah 5 Batch beberapa query dalam satu permintaan

Keuntungan praktis terbesar GraphQL adalah kemampuan untuk menamai dan mengirim beberapa kueri independen dalam satu HTTP POST. Gunakan alias kueri untuk menghindari konflik nama lapangan setiap alias menjadi kunci terpisah di data respon objek.

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

Respon membawa ketiga hasil dalam satu muatan:

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

Langkah 6 Python klien

Pola di bawah ini membungkus permintaan GraphQL dalam pembantu kecil sehingga kode aplikasi Anda tetap dapat dibaca.

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

Langkah 7 JavaScript / Node.js klien

Orang asli. fetch API (Node.js 18+) menangani permintaan GraphQL dengan boilerplate minimal. Pola mencerminkan Python helper di atas.

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

Langkah 8 Mengatasi kesalahan dengan sopan

GraphQL mengembalikan HTTP 200 bahkan ketika sebuah bidang query gagal. Kesalahan muncul di tingkat atas errors array di samping setiap parsial data yang berhasil. Periksa array ini sebelum menggunakan tanggapan alias yang gagal dalam kueri batch tidak akan mencegah alias lain dari mengembalikan data.

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

Langkah selanjutnya

Sekarang Anda dapat menanyakan titik akhir GraphQL dengan lancar, beberapa ekstensi alami akan membuat integrasi produksi siap:

• Jadwalkan pertanyaan sekitar waktu rilis. Gabungkan calendar pertanyaan dengan pola penjadwalan yang dijelaskan dalam Cara Menggunakan Release Calendar API untuk Jadwal Indikator Fetch bangun sebelum setiap pengumuman dan menembak announcements pertanyaan saat data baru dipublikasikan.
• Jelajahi seluruh skema secara interaktif. Jika Anda memiliki akses ke lingkungan developer dengan ENABLE_GRAPHIQL=trueBuka. /api/v1/graphql di browser Anda untuk menggunakan GraphiQL IDE built-in dengan otomatis dan dokumentasi inline untuk setiap bidang.
• Luangkan cakupan Anda untuk lebih banyak mata uang. Larilah. dataCatalogue untuk masing-masing mata uang yang didukung USD, EUR, GBP, AUD, CAD, JPY, CHF, dan NZD untuk membangun gambaran lengkap tentang data apa yang tersedia di seluruh dunia G8 FX.

Tim FXMacroData