البدء السريع: الاتصال بـ FXMacroData باستخدام Node.js

تم تصميم FXMacroData REST API ليتم استهلاكه من أي لغة يمكن أن تجعل طلب HTTP GET. يتم شحن Node.js مع fetch التطبيق من v18 فصاعداً، لذلك لا يوجد شيء إضافي لتثبيته للاستخدام الأساسي فقط مفتاح API الخاص بك وبضع خطوط من JavaScript. هذا الدليل يسيرك من الصفر إلى برنامج برمجي متعدد المؤشرات يعمل في أقل من عشر دقائق.

الشروط المسبقة

• Node.js 18 أو أحدث v18 قدمت العالمية fetch API؛ يوصى بـ v20+ لإنتاج
• npm (مجمعة مع Node.js) مطلوب فقط إذا اخترت إضافة حزم اختيارية
• مفتاح FXMacroData API التسجيل في / اشترك ونسخ مفتاحك من لوحة القيادة

تحقق من نسخة Node.js الخاصة بك:

node --version   # should print v18.x.x or later

الخطوة 1 تخزين مفتاح API الخاص بك بأمان

لا تقوم أبداً بتشفير مفتاح API في ملفات المصدر التي يمكن أن تكون ملتزمة بمراقبة الإصدارات. أبسط طريقة آمنة هي متغير البيئة الذي يتم قراءته في وقت التشغيل.

على لينكس / ماكوس، إضافة إلى ملف تعريف القشرة الخاص بك (~/.bashrc أو ~/.zshrc):

export FXMD_API_KEY="your_actual_api_key_here"

على ويندوز (باورشل):

$env:FXMD_API_KEY = "your_actual_api_key_here"

لمشاريع Node.js، .env الملف مع دوتينف الحزمة هي بديل شائع انظر الخطوة 6 لهذا الإعداد.

الخطوة 2 فهم شكل API

كل نقطة نهاية مؤشر FXMacroData تتبع نفس النمط، مما يجعل من السهل بناء مساعد استرجاع عام. إليك الهيكل الأساسي:

GET https://fxmacrodata.com/api/v1/announcements/{currency}/{indicator}?api_key=YOUR_API_KEY

الرد هو JSON مع مستوى أعلى data كل عنصر يحمل dateرقم val، و (بالنسبة لمعظم المؤشرات) announcement_datetime الذي يحدد الثانية التي تم فيها إطلاق القيمة:

{
  "data": [
    { "date": "2025-03-19", "val": 4.25, "announcement_datetime": "2025-03-19T18:00:00Z" },
    { "date": "2025-01-29", "val": 4.25, "announcement_datetime": "2025-01-29T19:00:00Z" },
    { "date": "2024-12-18", "val": 4.25, "announcement_datetime": "2024-12-18T19:00:00Z" }
  ]
}

هذا الهيكل النظيف والمتسق لا يتطلب أي تحويل تقريبا قبل استخدامها في المنطق التجاري أو قواعد البيانات أو واجهات برمجة التطبيقات في الأسفل.

الخطوة الثالثة: أول مكالمة لك

أنشئ ملفًا يدعى fxmd.js و أضف ما يلي. هذا يحضر سعر الفائدة السياسي لـ الاحتياطي الفيدرالي الأمريكي خلال العامين الماضيين باستخدام Node.js المدمج fetch.

// fxmd.js  —  requires Node.js 18+
const API_KEY = process.env.FXMD_API_KEY;
const BASE    = "https://fxmacrodata.com/api/v1";

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

  const res = await fetch(url.toString());
  if (!res.ok) {
    throw new Error(`API error ${res.status}: ${await res.text()}`);
  }
  const json = await res.json();
  return json.data ?? [];
}

// Fetch the Fed policy rate
const data = await getIndicator("usd", "policy_rate", "2023-01-01");
console.log(`Latest USD policy rate: ${data[0]?.val}% on ${data[0]?.date}`);

أطلقها

FXMD_API_KEY=your_key node fxmd.js

الخطوة 4 احصل على مؤشرات متعددة بالتوازي

Promise.all يطلق جميع الطلبات في وقت واحد، لذلك يستغرق استرداد عشرة مؤشرات تقريبا نفس وقت الساعة الجدارية كما استردادهم. هنا نمط قابلة لإعادة الاستخدام لسحب العديد من العملات والمؤشرات في وقت واحدة:

const CURRENCIES  = ["usd", "eur", "gbp", "aud", "jpy"];
const INDICATORS  = ["policy_rate", "inflation"];
const START       = "2024-01-01";

// Build a flat list of [currency, indicator] pairs
const pairs = CURRENCIES.flatMap(c => INDICATORS.map(i => [c, i]));

// Fire all requests in parallel
const results = await Promise.all(
  pairs.map(([currency, indicator]) =>
    getIndicator(currency, indicator, START)
      .then(data => ({ currency, indicator, latest: data[0] ?? null }))
      .catch(err => ({ currency, indicator, latest: null, error: err.message }))
  )
);

// Print a quick summary
for (const row of results) {
  if (row.error) {
    console.log(`${row.currency.toUpperCase()} ${row.indicator}: ERROR — ${row.error}`);
  } else if (row.latest) {
    console.log(
      `${row.currency.toUpperCase()} ${row.indicator}: ${row.latest.val} (${row.latest.date})`
    );
  }
}

- ... .catch في كل طلب يعني رد واحد سيء لا يمنع الدفعة بأكملها مفيدة عند تشغيل وظائف ليلية حيث لا تزال البيانات الجزئية قابلة للتنفيذ.

الخطوة 5 نص كامل جاهز للإنتاج

فيما يلي نص متوافق مع CommonJS كامل مع التعامل مع الأخطاء المناسبة، والعملة قابلة للتكوين وقوائم المؤشرات، والإخراج المنسق لتسجيل أو المعالجة في التداول:

// macro-snapshot.js  —  CommonJS, Node.js 18+
"use strict";

const API_KEY = process.env.FXMD_API_KEY;
const BASE    = "https://fxmacrodata.com/api/v1";

if (!API_KEY) {
  console.error("Error: FXMD_API_KEY environment variable is not set.");
  process.exit(1);
}

// ── Configuration ──────────────────────────────────────────────────────────
const CURRENCIES = ["usd", "eur", "gbp", "cad", "jpy", "aud", "nzd", "chf"];
const INDICATORS = ["policy_rate", "inflation", "unemployment"];
const START_DATE = "2024-01-01";
// ───────────────────────────────────────────────────────────────────────────

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

  const res = await fetch(url.toString());
  if (!res.ok) {
    const body = await res.text().catch(() => "");
    throw new Error(`HTTP ${res.status}${body ? ": " + body.slice(0, 120) : ""}`);
  }
  const json = await res.json();
  return Array.isArray(json.data) ? json.data : [];
}

async function main() {
  const pairs = CURRENCIES.flatMap(c => INDICATORS.map(i => [c, i]));

  const results = await Promise.all(
    pairs.map(async ([currency, indicator]) => {
      try {
        const data = await getIndicator(currency, indicator, START_DATE);
        return { currency, indicator, latest: data[0] ?? null, error: null };
      } catch (err) {
        return { currency, indicator, latest: null, error: err.message };
      }
    })
  );

  // Group by currency for readable output
  const byCurrency = {};
  for (const row of results) {
    if (!byCurrency[row.currency]) byCurrency[row.currency] = [];
    byCurrency[row.currency].push(row);
  }

  console.log("\n=== FXMacroData Macro Snapshot ===\n");
  for (const [currency, rows] of Object.entries(byCurrency)) {
    console.log(`  ${currency.toUpperCase()}`);
    for (const row of rows) {
      if (row.error) {
        console.log(`    ${row.indicator.padEnd(20)} — error: ${row.error}`);
      } else if (row.latest) {
        console.log(
          `    ${row.indicator.padEnd(20)} ${String(row.latest.val).padStart(8)}  (${row.latest.date})`
        );
      } else {
        console.log(`    ${row.indicator.padEnd(20)} — no data`);
      }
    }
    console.log();
  }
}

main().catch(err => {
  console.error("Fatal:", err.message);
  process.exit(1);
});

اطلق النص

FXMD_API_KEY=your_key node macro-snapshot.js

مخرج العينة:

=== FXMacroData Macro Snapshot ===

  USD
    policy_rate             4.25  (2025-03-19)
    inflation               2.40  (2025-04-10)
    unemployment            4.20  (2025-04-04)

  EUR
    policy_rate             2.40  (2025-04-17)
    inflation               2.20  (2025-04-16)
    unemployment            6.10  (2025-03-31)

  GBP
    policy_rate             4.50  (2025-03-20)
    inflation               2.60  (2025-03-26)
    unemployment            4.40  (2025-04-15)
  ...

الخطوة 6 استخدام "دوتينف" للتنمية المحلية

عند بناء مشروع Node.js أكبر من الأفضل أن تحتفظ بمفتاح API الخاص بك في .env و تحميلها تلقائياً مع دوتينف الحزمة:

npm install dotenv

إبتكر .env في ملف في جذر مشروعك (اضفها إلى .gitignore على الفور):

FXMD_API_KEY=your_actual_api_key_here

أضف سطر واحد في الجزء العلوي من النص:

require("dotenv").config();   // CommonJS
// or
import "dotenv/config";       // ES module

بقية النص تقول process.env.FXMD_API_KEY تماماً كما كان من قبل لا حاجة إلى أي تغييرات أخرى.

الخطوة 7 استكشاف الكتالوج الكامل للمؤشرات

الصورة الكلية أعلاه تغطي ثلاثة مؤشرات، ولكن FXMacroData تعرض أكثر من 80 سلسلة زمنية عبر 14 كتلة عملة رئيسية. getIndicator يعمل مساعد لكل منهم فقط تبادل العملة والإشارة سلغ. بضعة أمثلة عالية القيمة لتجار الفوركس:

• أسعار الفائدة الحقيقية إزالة inflation من policy_rate لتحديد الفارق في سعر الفائدة الحقيقي بين عملتين، وهو محرك رئيسي لتوجيه العملات على المدى المتوسط. أسعار سعر العملة الأمريكية لمعلومات عن النتيجة النهائية.
• بيانات العمل unemployment- لا non_farm_payrollsو average_hourly_earnings (USD) تعطي إشارات مبكرة على وظائف رد فعل البنك المركزي.
• مشاعر consumer_confidence- لا pmiو business_confidence ويمكن أن تتقدم على مؤشرات البيانات الصلبة بفترة من شهر إلى شهرين ويمكن لها أن تتبقى قبل تحركات العملات قبل أن تظهر في قرارات أسعار الفائدة.
• التدفقات التجارية trade_balance- لا exportsو imports ربط أزواج السلع والعملات (AUD، NZD، CAD) بتغيرات شروط التداول.

اطلع على الكتالوج الكامل لأي عملة على https://fxmacrodata.com/api/v1/catalogue/{currency}?api_key=YOUR_API_KEYأو استكشف المستندات التفاعلية على أداة بيانات api-data-docs.

ملخص

لديك الآن كل ما تحتاجه لاستهلاك FXMacroData من Node.js:

• عادي getIndicator(currency, indicator, startDate) مساعد الذي يتعامل مع التحقق والخطأ
• طلبات متعددة المؤشرات بالتوازي عبر Promise.all مع عزل الخطأ لكل طلب
• نص نص جاهز للإنتاج يمكنك تحديد الموعد، ونشره إلى وظيفة بدون خادم، أو دمجها في Node.js الخلفية القائمة
• إدارة مفتاح API الآمنة عبر متغيرات البيئة أو dotenv

الخطوات التالية الطبيعية: جدولة نص للفيديو باستخدام وظيفة كرون أو مشغل مهام مثل n8n، دفع النتائج إلى قاعدة بيانات، أو تغذيتها في خوارزمية التداول. نفس بنية JSON النظيفة التي يقرأها البرنامج النصي تعمل بشكل متطابق سواء كنت تبني لوحة تحكم React أو API Express أو محفز وظيفة Cloud.

لمزيد من الدلائل الخاصة باللغة انظر دليل البدء السريع قسم تغطي المخططات المباشرة لـ Python و R نفس مجموعة المؤشرات مع أدوات خاصة بالنظام البيئي لتحليل وتصورها.