How to Use the Release Calendar API to Schedule Indicator Fetches

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

لماذا الجدول الزمني بدلا من الاستطلاع؟

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

الخطوة 1 - فهم استجابة التقويم

تقويم الإصدار يعيد كائن JSON مع data كل صف يتضمن إصدار الحصيرة وخط الزمني المقرر UTC.

curl "https://fxmacrodata.com/api/v1/calendar/usd?indicator=inflation"

شكل الاستجابة:

{
  "currency": "USD",
  "indicator": "inflation",
  "data": [
    {
      "announcement_datetime": 1773077400,
      "release": "inflation"
    }
  ]
}

بالنسبة للعملات غير الدولار الأمريكي، حافظ على نفس الطريق وأضف api_key كبارامتر استفسار. إذا كنت تستفسر جدول العملات الأوسع دون مرشح مؤشر، قد تتضمن بعض الصفوف أيضًا بيانات بيانات التوجيه مثل endpoint_family أو endpoint_path.

الخطوة 2 - ابحث عن الطابع الزمني التالي للإصدار

يسأل المساعد أدناه عن تقويم الإنتاج لمؤشر واحد ويرد أول طابع زمني مستقبلي.

import time
import requests

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

def next_release(currency: str, indicator: str, api_key: str | None = None) -> float | None:
    url = f"{BASE}/calendar/{currency}"
    params = {"indicator": indicator}
    if api_key:
        params["api_key"] = api_key

    response = requests.get(url, params=params, timeout=10)
    response.raise_for_status()

    now = time.time()
    for row in response.json().get("data", []):
        ts = row.get("announcement_datetime")
        if row.get("release") == indicator and ts and float(ts) > now:
            return float(ts)
    return None

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

عندما يصل الطابع الزمني، اتصل بإعلانات المطابقة نقطة النهاية وقرأ أحدث ملاحظة من العودة data المجموعة

def wait_and_fetch(currency: str, indicator: str, api_key: str | None = None) -> dict | None:
    release_ts = next_release(currency, indicator, api_key)
    if release_ts is None:
        print(f"No upcoming release found for {currency}/{indicator}.")
        return None

    wake_at = release_ts - 2
    time.sleep(max(0.0, wake_at - time.time()))

    url = f"{BASE}/announcements/{currency}/{indicator}"
    params = {"api_key": api_key} if api_key else {}
    response = requests.get(url, params=params, timeout=10)
    response.raise_for_status()
    return response.json()

الخطوة 4 - بناء حلقة مستمرة

import time
import requests

BASE = "https://fxmacrodata.com/api/v1"
API_KEY = None
CURRENCY = "usd"
INDICATOR = "inflation"

def on_release(payload: dict) -> None:
    rows = payload.get("data", [])
    latest = rows[-1] if rows else {}
    print(
        "New release:",
        latest.get("date"),
        "value=", latest.get("val"),
        "announced_at=", latest.get("announcement_datetime"),
    )

while True:
    release_ts = next_release(CURRENCY, INDICATOR, API_KEY)
    if release_ts is None:
        print("No release found in the current calendar window. Retrying in 24 hours.")
        time.sleep(86_400)
        continue

    sleep_seconds = max(0.0, release_ts - 2 - time.time())
    print(f"Next {CURRENCY.upper()} {INDICATOR} release in {sleep_seconds / 3600:.2f}h")
    time.sleep(sleep_seconds)

    payload = wait_and_fetch(CURRENCY, INDICATOR, API_KEY)
    if payload:
        on_release(payload)

    time.sleep(5)

توقف قصير بعد الإصدار يعطي النظام الوقت لتحريك الحدث المقرر إلى الأمام قبل استفسار التقويم التالي.

الخطوة 5 - التوسع إلى ساعات متعددة

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

WATCHES = [
    {"currency": "usd", "indicator": "inflation"},
    {"currency": "usd", "indicator": "gdp"},
    {"currency": "aud", "indicator": "policy_rate"},
    {"currency": "gbp", "indicator": "unemployment"},
]

لمزيد من التفاصيل عن الميدان حول عمليات الاستلام التالية، انظر سعر سعر العملة الأسترالية- لا البطالة في الجنيه الإسترليني، وبقية المعلومات في مؤشر المستندات.

الخطوة 6 - JavaScript / Node.js المتغير

نفس النمط يترجم مباشرة إلى Node.js: استفسار التقويم مع مرشح مؤشر، النوم حتى العلامة الزمنية التي تم إرجاعها، ثم احضار مسار الإعلانات المطابقة.

const BASE = "https://fxmacrodata.com/api/v1";

async function nextRelease(currency, indicator, apiKey) {
  const url = new URL(`${BASE}/calendar/${currency}`);
  url.searchParams.set("indicator", indicator);
  if (apiKey) url.searchParams.set("api_key", apiKey);

  const response = await fetch(url);
  if (!response.ok) throw new Error(`Calendar request failed: ${response.status}`);

  const payload = await response.json();
  const now = Date.now() / 1000;
  return payload.data.find((row) => row.release === indicator && row.announcement_datetime > now) ?? null;
}

async function fetchAnnouncement(currency, indicator, apiKey) {
  const url = new URL(`${BASE}/announcements/${currency}/${indicator}`);
  if (apiKey) url.searchParams.set("api_key", apiKey);

  const response = await fetch(url);
  if (!response.ok) throw new Error(`Announcement request failed: ${response.status}`);
  return response.json();
}

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