كيفية استخدام جميع نقاط نهاية FXMacroData API: دليل كامل

بحلول نهاية هذا الدليل سيكون لديك أمثلة عمل لكل نقطة نهاية عامة في FXMacroData API من سلسلة الإعلانات وتقويم الإصدارات إلى وضع COT وأسعار المعادن الثمينة وأسعار الفوركس وواجهة GraphQL حتى تتمكن من اختيار الأداة المناسبة لأي سير عمل بيانات الماكرو.

الخطوة 1 الإعلانات: سلسلة المؤشرات التاريخية

نقطة نهاية الإعلانات هي جوهر FXMacroData. إنها تعيد سلسلة زمنية موحدة ومعطومة زمنيا لأي مؤشر اقتصادي كلي مدعوم. يحمل كل سطر تاريخ الملاحظة والقيمة المنشورة والختم الزمني الدقيق لـ Unix للنشر الرسمي مما يمنحك دقة مستوى ثانية للبحث القائم على الأحداث والاختبار الخلفي.

طلبات الدولار الأمريكي تعمل بدون مفتاح API. لأي عملة أخرى، أضف مفتاحك كمعلم استفسار. استخدم start_date و end_date (YYY-MM-DD) لتضييق النافذة، والخيار الافتراضي هو آخر 365 يوما.

# USD inflation series — no key needed
curl "https://fxmacrodata.com/api/v1/announcements/usd/inflation"

# AUD policy rate — Pro key required
curl "https://fxmacrodata.com/api/v1/announcements/aud/policy_rate?api_key=YOUR_API_KEY"

# EUR GDP with a custom date range
curl "https://fxmacrodata.com/api/v1/announcements/eur/gdp?start_date=2024-01-01&end_date=2026-03-01&api_key=YOUR_API_KEY"

{
  "currency": "USD",
  "indicator": "inflation",
  "has_official_forecast": false,
  "start_date": "2025-03-01",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-02-01",
      "val": 2.8,
      "announcement_datetime": 1741082400,
      "pct_change": -0.5,
      "pct_change_12m": -6.7
    }
  ]
}

- ... announcement_datetime المجال هو ختم وقت يونيكس (ثواني، UTC) لللحظة الدقيقة التي تم فيها نشر البيانات رسمياً. استخدمه لتوجيه دراسة الحدث وتجنب التحيز في الاختبارات الخلفية. تصفح خفافيش المؤشر المتاحة لأي عملة مع كتالوج البيانة (الخطوة 3) أو في مستندات بيانات واجهة برمجة التطبيقات.

الخطوة 2 تقويم الإصدارات: أوقات الإعلان القادمة

تعيد نقطة نهاية التقويم الطوابع الزمنية المقررة لإعلان UTC لكل إصدار كبير قادم لعملة معينة. استخدمه لجدولة عملية استرداد مستهدفة يتم إطلاقها عند نشر بيانات جديدة بدلاً من الاستطلاع باستمرار على فترة زمنية ثابتة.

لا يتطلب مفتاح API. تصفية إلى مؤشر معين مع الاختيارية indicator معيار الاستعلام رمز العملة الخاصة COMM يعيد جدول إطلاق السلع.

# All upcoming releases for USD
curl "https://fxmacrodata.com/api/v1/calendar/usd"

# Filter to a single indicator
curl "https://fxmacrodata.com/api/v1/calendar/usd?indicator=non_farm_payrolls"

# Commodity release schedule
curl "https://fxmacrodata.com/api/v1/calendar/COMM"

{
  "currency": "USD",
  "indicator": "non_farm_payrolls",
  "data": [
    {
      "release": "non_farm_payrolls",
      "announcement_datetime": 1746540600,
      "requires_api_key": false
    }
  ]
}

تحويل العلامة الزمنية إلى وقت UTC قابل للقراءة من قبل الإنسان مع datetime.fromtimestamp(ts, tz=timezone.utc) في بايثون أو new Date(ts * 1000).toISOString() في جافا سكريبت. لمعرفة نمط جدولة كامل، انظر كيفية استخدام واجهة برمجة برمجة التطبيقات التقويمية لإعداد جدول إصدارات مؤشرات.

الخطوة 3 كتالوج البيانات: اكتشاف المؤشرات المتاحة

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

# List all indicators for EUR — no key required
curl "https://fxmacrodata.com/api/v1/data_catalogue/eur"

# Include routing and auth discovery metadata per indicator
curl "https://fxmacrodata.com/api/v1/data_catalogue/usd?include_capabilities=true"

{
  "gdp": {
    "name": "GDP Growth",
    "unit": "%QoQ",
    "frequency": "Quarterly",
    "has_official_forecast": false
  },
  "inflation": {
    "name": "Inflation (CPI)",
    "unit": "%YoY",
    "frequency": "Monthly",
    "has_official_forecast": false
  },
  "policy_rate": {
    "name": "Policy Rate",
    "unit": "%",
    "frequency": "Meeting",
    "has_official_forecast": true
  }
}

المفاتيح العليا في الإجابة هي نفسها {indicator} النقود المدعومة تشمل الدولار الأمريكي، اليورو، الجنيه الإسترليني، اليابانية، الدولار الأسترالي، الكاد، الفرنك السويسري، الدين الاوروبي، اليوراني الصيني، الدرياني السويدي، الكروين السويدية، الدنك الدنماركي، البلنك الروسي، والبرليني. include_coverage=true للحصول على شبكة توافر العملات عبر في استجابة واحدة.

الخطوة 4 تحديد المواقع في الموقع: بيانات العقود الآجلة المضاربة

توفر نقطة نهاية التزام المتداولين بيانات وضع أسبوعية لـ CFTC لعقود العقود الآجلة للعملات الأجنبية. إنها تظهر إجمالي الفائدة المفتوحة بين المشاركين غير التجاريين (المضاربة) والتجاري (المتداولون) وغير الواجب الإبلاغ عنهم مؤشر رائد على نطاق واسع لعكس اتجاه العملات والوضع المزدحم.

العملات المدعومة: الدولار الأمريكي، اليورو، الجنيه الإسترليني، اليابانية، الدولار الأسترالي، الكاد، الفرنك السويسري، الدينار النيوزيلندي. الدولار هو مجاني؛ جميع العملات الأخرى تتطلب مفتاح بروف.

# USD COT history — free
curl "https://fxmacrodata.com/api/v1/cot/usd"

# EUR COT with a custom date range
curl "https://fxmacrodata.com/api/v1/cot/eur?start_date=2025-01-01&api_key=YOUR_API_KEY"

{
  "currency": "EUR",
  "instrument": "EURO FX - CHICAGO MERCANTILE EXCHANGE",
  "fx_overlay": { "pair": "EUR/USD" },
  "start_date": "2025-01-07",
  "end_date": "2026-03-25",
  "data": [
    {
      "date": "2026-03-18",
      "announcement_datetime": 1742493000,
      "open_interest": 812345,
      "noncommercial_long": 185000,
      "noncommercial_short": 92000,
      "noncommercial_net": 93000,
      "commercial_long": 203000,
      "commercial_short": 310000,
      "commercial_net": -107000,
      "nonreportable_long": 21000,
      "nonreportable_short": 9000
    }
  ]
}

- ... noncommercial_net المجال المضاربة طويلة ناقص قصيرة هو مقياس الموقع الأكثر شيوعا للمتداولين في الفوركس. announcement_datetime for the Friday 3:30 PM ET CFTC publication. For EUR pair context see the أسعار سعر العملة في اليورو.

الخطوة 5 المعادن: أسعار الذهب والفضة والبلاتين

تعيد نقطة نهاية المعادن سلسلة الأسعار اليومية للمعادن الثمينة المشتقة من الصندوق الملكي (إصلاحات LBMA). هذه السلسلة مفيدة كمدخلات macro عبر الأصول ، خاصة لتتبع تدفقات الملاذ الآمن والديناميكيات المرتبطة بالدولار الأمريكي.

مطلوب دائماً مفتاح API المهني لهذه النقطة النهائية. gold- لا silver- لا platinum.

# Gold LBMA PM Fix daily prices
curl "https://fxmacrodata.com/api/v1/commodities/gold?api_key=YOUR_API_KEY"

# Silver with a date range
curl "https://fxmacrodata.com/api/v1/commodities/silver?start_date=2025-01-01&api_key=YOUR_API_KEY"

# Platinum spot
curl "https://fxmacrodata.com/api/v1/commodities/platinum?api_key=YOUR_API_KEY"

{
  "currency": "COMM",
  "indicator": "gold",
  "has_official_forecast": false,
  "start_date": "2025-03-30",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-03-28",
      "val": 2870.00,
      "pct_change": 1.2,
      "pct_change_12m": 30.1
    }
  ]
}

شكل الرد هو نفس نقطة نهاية الإعلانات، لذلك يمكنك إعادة استخدام نفس رمز التحليل. لاحظ أن announcement_datetime هو null لسلسلة الأسعار اليومية ويتم تعبئتها فقط للأحداث الرسمية للنشر الشهري.

الخطوة 6 أسعار الفوركس: سلسلة أسعار فورية يومية

تعيد نقطة نهاية الفوركس بيانات سعر الفورية اليومية لـ OHLC لأي زوج عملات مدعوم. لا يلزم مفتاح API. استخدمه لتوفير إصدارات مؤشر الماكرو مع سعر الصرف المعاصر لتحليل الخلفية أو سير العمل في تصور الرسم البياني.

تمرير القاعدة والاقتباس كقطاعات مسار منفصلة (مثل /forex/eur/usd إضافة التداخلات بين المؤشرات الفنية مع indicators معيار الاستفسار

# EUR/USD daily rates — no key required
curl "https://fxmacrodata.com/api/v1/forex/eur/usd"

# AUD/JPY with a custom date range
curl "https://fxmacrodata.com/api/v1/forex/aud/jpy?start_date=2025-01-01"

# GBP/USD with technical indicators overlaid
curl "https://fxmacrodata.com/api/v1/forex/gbp/usd?indicators=sma_20,rsi_14"

{
  "base": "EUR",
  "quote": "USD",
  "start_date": "2025-03-30",
  "end_date": "2026-03-30",
  "data": [
    {
      "date": "2026-03-28",
      "close": 1.0832,
      "open": 1.0821,
      "high": 1.0867,
      "low": 1.0798
    }
  ]
}

الخطوة 7 جلسات السوق: حالة الدورة في الوقت الحقيقي

تعيد نقطة نهاية جلسات السوق الحالة الحالية لفتح / إغلاق جميع جلسات الفوركس الرئيسية الأربعة سيدني وطوكيو ولندن ونيويورك مع نوافذ التداخل النشطة. لا يلزم مفتاح API. استخدمه لفتح الأتمتة الحساسة للوقت إلى نوافذة الذروة السيولة أو لتعليق الرسوم البيانية مع حدود الجلسة.

# Real-time snapshot — no key required
curl "https://fxmacrodata.com/api/v1/market_sessions"

# Historical snapshot for scheduling or testing
curl "https://fxmacrodata.com/api/v1/market_sessions?at=2026-03-28T12:00:00Z"

{
  "now_utc": "2026-03-30T08:47:00Z",
  "now_unix": 1743324420,
  "is_market_day": true,
  "sessions": [
    {
      "name": "London",
      "is_open": true,
      "seconds_to_close": 25200,
      "currencies": ["EUR", "GBP", "CHF"],
      "open_utc": "2026-03-30T07:00:00Z",
      "close_utc": "2026-03-30T15:00:00Z"
    }
  ],
  "overlaps": [
    {
      "name": "London / New York",
      "is_active": false,
      "priority": "high",
      "start_utc": "2026-03-30T12:00:00Z",
      "end_utc": "2026-03-30T16:00:00Z",
      "notable_pairs": ["EUR/USD", "GBP/USD", "USD/CHF"],
      "duration_hours": 4
    }
  ]
}

التداخل بين لندن ونيويورك هو أعلى نافذة السيولة في يوم التداول، وهو عندما يسبب الإصدارات الكبرى في معظم الأحيان أكبر التحركات الفورية. is_market_day: false لتجاوز الأتمتة في عطلات نهاية الأسبوع وأيام العطل الرئيسية في الأسواق.

الخطوة 8 GraphQL: مجموعة استفسارات متعددة في طلب واحد

FXMacroData تعرض نقطة نهاية GraphQL التي تعكس سطح REST بالضبط نفس قواعد المصادقة، نفس أسماء الحقول، نفس البيانات ولكن يسمح لك بإعلان فقط الحقول التي تحتاج إليها ودمج استفسارات متعددة في رحلة ذهاب وإياب HTTP واحدة. إذا كنت بحاجة إلى تضخم EUR و سعر الفائدة المحدد للجنيه الإسترليني و تقويم إصدار AUD، وهذا هو واحد POST بدلا من ثلاثة GETs.

ارسل POST إلى https://fxmacrodata.com/api/v1/graphql مع جسم JSON يحتوي على query المفتاح الخاص بك و API المفتوحة كمعلمة استفسار URL. الحقول الجذرية المتاحة هي announcements- لا dataCatalogueو calendar.

# Single free USD query — no key required
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 } } }"
  }'

# Batched: EUR inflation + GBP policy rate in one request
curl -s -X POST "https://fxmacrodata.com/api/v1/graphql?api_key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { eurCPI: announcements(currency: \"EUR\", indicator: \"inflation\") { data { date val } } gbpRate: announcements(currency: \"GBP\", indicator: \"policy_rate\") { data { date val } } }"
  }'

{
  "data": {
    "eurCPI":  { "data": [{ "date": "2026-02-28", "val": 2.3 }] },
    "gbpRate": { "data": [{ "date": "2026-03-20", "val": 4.5 }] }
  }
}

يعيد GraphQL HTTP 200 حتى عندما تفشل حقل الاستفسار errors صفحة جنبا إلى جنب مع أي بيانات جزئية ناجحة. تحقق دائمًا من وجود تلك الصفحة قبل معالجة الاستجابة. لممارسة كاملة من Python و JavaScript مع التعامل مع الأخطاء وأنماط التفريق ، انظر كيفية استفسار FXMacroData عن طريق GraphQL.

الخطوة 10 سير العمل من نهاية إلى نهاية بايثون

المقطع أدناه يجمع بين الأنماط الأكثر شيوعًا بالتسلسل: اكتشاف المؤشرات المتاحة ، والتحقق من الإصدار المقرر التالي ، والحصول على سلسلة مؤشرات في طلب GraphQL واحد ، ثم التحقق الشرطي من حالة جلسة السوق قبل توجيه الناتج.

import requests
from datetime import datetime, timezone

BASE = "https://fxmacrodata.com/api/v1"
API_KEY = "YOUR_API_KEY"


def params(require_key: bool = True) -> dict:
    return {"api_key": API_KEY} if require_key else {}


# 1. Discover available indicators for AUD (free)
catalogue = requests.get(f"{BASE}/data_catalogue/aud", params=params(False), timeout=10)
catalogue.raise_for_status()
print("AUD indicators:", list(catalogue.json().keys())[:5])

# 2. Check the next USD non-farm payrolls release timestamp (free)
cal = requests.get(f"{BASE}/calendar/usd", params={"indicator": "non_farm_payrolls"}, timeout=10)
cal.raise_for_status()
events = cal.json().get("data", [])
if events:
    ts = events[0]["announcement_datetime"]
    dt = datetime.fromtimestamp(ts, tz=timezone.utc)
    print(f"Next NFP release: {dt.strftime('%Y-%m-%d %H:%M UTC')}")

# 3. Fetch EUR inflation + AUD policy rate in one GraphQL request (Pro key)
gql_query = """
query {
  eurCPI: announcements(currency: "EUR", indicator: "inflation") {
    data { date val pctChange }
  }
  audRate: announcements(currency: "AUD", indicator: "policy_rate") {
    data { date val }
  }
}
"""
resp = requests.post(
    f"{BASE}/graphql",
    params={"api_key": API_KEY},
    json={"query": gql_query},
    timeout=15,
)
resp.raise_for_status()
payload = resp.json()
if "errors" in payload:
    raise RuntimeError(payload["errors"])
data = payload["data"]

eur_latest = data["eurCPI"]["data"][-1]
aud_latest = data["audRate"]["data"][-1]
print(f"EUR CPI  {eur_latest['date']}: {eur_latest['val']}%")
print(f"AUD Rate {aud_latest['date']}: {aud_latest['val']}%")

# 4. Check market sessions before triggering a trade alert (free)
sessions_resp = requests.get(f"{BASE}/market_sessions", timeout=10)
sessions_resp.raise_for_status()
session_data = sessions_resp.json()

if session_data["is_market_day"]:
    for overlap in session_data.get("overlaps", []):
        if overlap["is_active"] and overlap["priority"] == "high":
            print(f"High-liquidity window active: {overlap['name']}")
else:
    print("Market closed — skipping alert")

ما الذي يمكنك بناءه بعد ذلك

لديك الآن أمثلة عمل لكل نقطة نهاية عامة في FXMacroData API.

• استبدال المكالمات المتتالية REST مع GraphQL التفريغ. في أي مكان تقوم به ثلاث أو أكثر طلبات GET مستقلة، يمكن أن يحل محل GraphQL POST واحد. كيفية استفسار FXMacroData عن طريق GraphQL. .
• وضع الطبقة COT على اختلافات السعر. Combine the speculative net from the COT endpoint with the policy rate series to build a composite macro signal across the G8 currency universe.
• المواءمة بين أسعار المعادن مع إطلاق العملات. اقترن الذهب من نقطة النهاية للمعادن مع سلسلة الإعلانات AUD أو USD لتتبع ارتباطات الملاذ الآمن والدولار بمرور الوقت.

فريق FXMacroData