How To Query Fxmacrodata Via Graphql

بحلول نهاية هذا الدليل سوف تكون قادرة على استفسار أي مؤشر اقتصادية كلية، واكتشاف الكتالوج الكامل للبيانات المتاحة، والتحقق من تواريخ الإصدار القادمة من خلال جميع FXMacroData نقطة نهاية GraphQL لا تستخدم شيئاً أكثر من curlسوف تعرف أيضا كيفية تجميع عدة استفسارات في رحلة ذهاب وعودة واحدة حتى تتمكن البرامج النصية الخاصة بك من البقاء نحيلة وسريعة.

لماذا GraphQL بدلا من REST؟

يقدم FXMacroData REST API خدمة لكل مؤشر في نقطة نهائية خاصة به رحلة ذهاب وإياب واحدة لكل تركيبة من العملة / المؤشر. يتيح لك GraphQL إعلان الحقول التي تحتاج إليها بالضبط ودمج عدة استعلامات مستقلة في طلب HTTP واحد. إذا كنت تريد سلسلة تضخم EUR و سعر الفائدة الرئيسي لجنيه إسترليني و التقويم القادم للإصدار لكلتا العملتين، أي طلب واحد POST بدلا من أربعة طلبات GET.

سطح GraphQL يعكس نقاط النهاية العامة REST بالضبط: نفس قواعد المصادقة، نفس البيانات، وأسماء الحقول نفسها فقط خدمة من خلال واحد POST /api/v1/graphql نقطة نهاية مع جسم JSON.

الخطوة 1 إرسال أول استفسار GraphQL الخاص بك

كل طلب GraphQL هو كائن JSON مع query مفتاح قيمته هو سلسلة استفسار GraphQL الخاصة بك. ابدأ باستخدام استفسar التضخم المجانية USD لا حاجة إلى مفتاح 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 } } }"
  }'

الرد هو GraphQL JSON القياسية ملفوفة في data المظروف:

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

لأي عملة غير الدولار الأمريكي، أضف مفتاح API الخاص بك كمعلم استفسار على عنوان URL النقطة النهائية:

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

الخطوة 2 اكتشاف المؤشرات المتاحة مع dataCatalogue

قبل استفسار مؤشر معين يمكنك أن تسأل API ما هي البيانات التي لديها لأي عملة. dataCatalogue يرد الاستعلام كل خفاش مؤشر متاح، واسمه القابل للقراءة من قبل الإنسان، وحدة، وتكرار الإفراج عنه، وما إذا كان البنك المركزي ينشر توقعات رسمية له.

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

مثال على الرد (مختصر):

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

- ... slug القيم هي السلاسل التي تمر بها indicator الحجة في وقت لاحق announcements يمكنك تصفح الكتالوج الكامل للمؤشرات بشكل تفاعلي في مستندات بيانات واجهة برمجة التطبيقات.

الخطوة 3 احصل على البيانات التاريخية مع مرشحات التواريخ الاختيارية

- ... announcements الاستفسار يقبل اختياري startDate و endDate الحجج في YYYY-MM-DD البيانات التي يتم تقديمها في الموقع الإلكتروني من خلال البنك المركزي في البنك الأوروبي.

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

أبرز ردود الأفعال:

{
  "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 هو طابع زمني يونيكس (ثواني، UTC) من المنشور الرسمي. يمكنك العثور على وثائق مستوى الميدان لمؤشرات AUD في وثائق أسعار الفائدة السياسية للدولار الأسترالي.

الخطوة 4 استفسار تقويم الإصدار

- ... calendar تسترد استفسار أوقات الإعلان المقررة UTC لكل إصدار مؤشر قادم لعملة معينة. تمرير اختيارية indicator الحجة لتضييق النتائج إلى مؤشر واحد.

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

إلتفت announcementDatetime إلى وقت UTC قابل للقراءة من قبل الإنسان في بايثون مع datetime.utcfromtimestamp(1745917200)أو في جافا سكريبت مع new Date(1745917200 * 1000).toISOString()لمزيد من التفاصيل عن مؤشر تضخم الجنيه الإسترليني انظر وثائق تضخم الجنيه الإسترليني.

الخطوة 5 مجموعة من الاستفسارات المتعددة في طلب واحد

أكبر ميزة عملية لـ GraphQL هي القدرة على تسمية وإرسال عدة استفسارات مستقلة في HTTP POST واحد. استخدم أسماء مستعارة لتحذير تضارب أسماء الحقول كل اسم مستعار يصبح مفتاحًا منفصلًا في data موضوع الرد

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

الإجابة تحمل كل النتائج الثلاثة في حمولة واحدة:

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

الخطوة 6 مستخدم بايثون

النمط أدناه يلف طلبات GraphQL في مساعد صغير حتى يبقى رمز تطبيقك قابلا للقراءة. يدعم الاستفسارات الفردية واستفسارات الأسماء المستعارة المجموعة بنفس الوظيفة.

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

الخطوة 7 JavaScript / Node.js العميل

الوطني fetch API (Node.js 18+) تتعامل مع طلبات GraphQL مع الحد الأدنى من الحجم. ينعكس النمط مساعد Python أعلاه.

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

الخطوة 8 تعامل مع الأخطاء بكرامة

يعيد GraphQL HTTP 200 حتى عندما تفشل حقل الاستفسار. تظهر الأخطاء في مستوى أعلى errors تفرق بجانب أي جزء 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"])

الخطوات التالية

الآن بعد أن يمكنك استفسار نقطة نهاية GraphQL بسلاسة، بضعة إضافات طبيعية ستجعل عملية التكامل جاهزة للإنتاج:

• جدّد استفسارات حول أوقات الإفراج. - إجمعوا calendar استفسار مع نمط الجدول الزمني الموصوف في كيفية استخدام واجهة برمجة برمجة التطبيقات التقويمية لإعداد جدول إصدارات المؤشرات استيقظ قبل كل إعلان و اطلق النار announcements في اللحظة التي يتم فيها نشر بيانات جديدة.
• استكشف المخطط الكامل بشكل تفاعلي إذا كان لديك إمكانية الوصول إلى بيئة تطوير ENABLE_GRAPHIQL=true، مفتوحة /api/v1/graphql في متصفحك لاستخدام GraphiQL IDE المدمج مع التكمل التلقائي والوثائق المتضمنة لكل حقل.
• توسيع تغطيتك إلى عملات أكثر. إهرب dataCatalogue لكل عملة مدعومة USD، EUR، GBP، AUD، CAD، JPY، CHF، و NZD لبناء صورة كاملة عن ما هي البيانات المتاحة في جميع أنحاء عالم G8 FX.

فريق FXMacroData