انتقل إلى المحتوى الرئيسي
QuantanSite

مرجع API

توثيق API

واجهة API بصيغة JSON للقراءة فقط فوق نفس بيانات السوق التي يعرضها هذا الموقع. تستخدم الاستجابات الناجحة غلاف { data, meta }، بينما تستخدم حالات الفشل غلاف { error: { code, message } }.

عنوان URL الأساسي
http://localhost:3000
الطرق
GET فقط
الصيغة
JSON, UTF-8
حد الطلبات
60 طلب لكل 60 ثانية، لكل عنوان IP ونقطة نهاية

These are API examples. This site is served as static files.

عرض تجريبي
تأتي الاستجابات من مجموعة بيانات تجريبية حتمية بأسماء مُصدِرين خيالية، ما لم يضبط الخادم MARKET_DATA_PROVIDER=fmp مع FMP_API_KEY. ويبيّن الحقل meta.provider في كل استجابة المصدر الذي أجاب.

قائمة عروض الأسعار

GET/api/quotes

يعيد صفحة واحدة من الأدوات كمصفوفة مسطحة، مع total و page و pageSize داخل meta. وكل مرشح من مرشحات الفحص أدناه يعمل هنا أيضًا؛ وتُهمل القيم التي يتعذر تحليلها.

المعاملات

المعاملالموقعالنوعمطلوبالوصف
sectorquerystringاختيارياسم القطاع بدقة: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate.
sortquerystringاختياريحقل الترتيب: marketCap (الافتراضي)، price، changePercent، volume أو symbol.
orderquerystringاختيارياتجاه الترتيب: desc (الافتراضي) أو asc.
pagequerynumberاختياريرقم الصفحة، بدءًا من 1.
pageSizequerynumberاختياريالصفوف في الصفحة: 20 افتراضيًا، و100 كحد أقصى.

الطلب

curl -s "http://localhost:3000/api/quotes?pageSize=3"

نموذج الاستجابة

200application/json

{
  "data": [
    {
      "symbol": "NWRB",
      "name": "Northwind Robotics",
      "exchange": "NASDAQ",
      "sector": "Technology",
      "industry": "Industrial Automation",
      "price": 733.8,
      "change": -16.52,
      "changePercent": -2.2,
      "previousClose": 750.32,
      "open": 750.03,
      "dayHigh": 751.29,
      "dayLow": 731.5,
      "volume": 3471317,
      "avgVolume": 2962633,
      "marketCap": 982258754565,
      "peRatio": 60.35,
      "eps": 12.16,
      "dividendYield": null,
      "week52High": 963.99,
      "week52Low": 583.89,
      "afterHoursPrice": 731,
      "afterHoursChangePercent": -0.38,
      "updatedAt": "2026-11-12T21:00:00.000Z"
    }
  ],
  "meta": {
    "provider": "demo",
    "generatedAt": "2026-11-12T21:00:04.512Z",
    "disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
    "total": 20,
    "page": 1,
    "pageSize": 3
  }
}

تم اختصار النموذج إلى صف واحد.

الحصول على عرض سعر

GET/api/quotes/{symbol}

يعيد عرض السعر الكامل لأداة أو مؤشر واحد. ويعيد الرمز غير المعروف 404 not_found.

المعاملات

المعاملالموقعالنوعمطلوبالوصف
symbolpathstringمطلوبرمز الأداة أو المؤشر، مثل NWRB. والمطابقة تتجاهل حالة الأحرف.

الطلب

curl -s "http://localhost:3000/api/quotes/NWRB"

نموذج الاستجابة

200application/json

{
  "data": {
    "symbol": "NWRB",
    "name": "Northwind Robotics",
    "exchange": "NASDAQ",
    "sector": "Technology",
    "industry": "Industrial Automation",
    "price": 733.8,
    "change": -16.52,
    "changePercent": -2.2,
    "previousClose": 750.32,
    "open": 750.03,
    "dayHigh": 751.29,
    "dayLow": 731.5,
    "volume": 3471317,
    "avgVolume": 2962633,
    "marketCap": 982258754565,
    "peRatio": 60.35,
    "eps": 12.16,
    "dividendYield": null,
    "week52High": 963.99,
    "week52Low": 583.89,
    "afterHoursPrice": 731,
    "afterHoursChangePercent": -0.38,
    "updatedAt": "2026-11-12T21:00:00.000Z"
  },
  "meta": {
    "provider": "demo",
    "generatedAt": "2026-11-12T21:00:04.512Z",
    "disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice."
  }
}

الحصول على الشموع

GET/api/candles/{symbol}

يعيد شموع OHLCV من الأقدم إلى الأحدث. ويستخدم النطاق 1D فواصل زمنية من 30 دقيقة، بينما تستخدم بقية النطاقات شموعًا يومية. ويعيد النطاق غير المعروف 400 bad_request.

المعاملات

المعاملالموقعالنوعمطلوبالوصف
symbolpathstringمطلوبرمز الأداة أو المؤشر، مثل NWRB. والمطابقة تتجاهل حالة الأحرف.
rangequerystringاختياريواحد من 1D, 5D, 1M, 6M, 1Y, 5Y. والافتراضي هو 1M.

الطلب

curl -s "http://localhost:3000/api/candles/NWRB?range=1M"

نموذج الاستجابة

200application/json

{
  "data": [
    {
      "time": "2026-11-11",
      "open": 757.4,
      "high": 761.18,
      "low": 743.92,
      "close": 750.32,
      "volume": 3531710
    },
    {
      "time": "2026-11-12",
      "open": 750.03,
      "high": 751.29,
      "low": 731.5,
      "close": 733.8,
      "volume": 3471317
    }
  ],
  "meta": {
    "provider": "demo",
    "generatedAt": "2026-11-12T21:00:04.512Z",
    "disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
    "symbol": "NWRB",
    "range": "1M"
  }
}

تم اختصار النموذج إلى شمعتين؛ ويعيد النطاق 1M عدد 22.

فحص الأدوات

GET/api/screener

يفلتر الأدوات ويرتبها ويقسّمها إلى صفحات بالمعاملات نفسها المستخدمة في صفحة الفحص. وتحتوي النتيجة على rows مع total و page و pageSize؛ وتُهمل القيم التي يتعذر تحليلها.

المعاملات

المعاملالموقعالنوعمطلوبالوصف
sectorquerystringاختيارياسم القطاع بدقة: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate.
minMarketCap, maxMarketCapquerynumberاختياريحدود القيمة السوقية بالدولار USD.
minPrice, maxPricequerynumberاختياريحدود السعر بالدولار USD.
minChangePercent, maxChangePercentquerynumberاختياريحدود التغير اليومي بالنقاط المئوية: -3 تعني -3%.
minVolumequerynumberاختياريالحد الأدنى لحجم التداول اليومي بالأسهم.
profitableOnlyquerystringاختيارياضبطه على 1 للإبقاء فقط على الأدوات التي يزيد فيها EPS على 0.
sortquerystringاختياريحقل الترتيب: marketCap (الافتراضي)، price، changePercent، volume أو symbol.
orderquerystringاختيارياتجاه الترتيب: desc (الافتراضي) أو asc.
pagequerynumberاختياريرقم الصفحة، بدءًا من 1.
pageSizequerynumberاختياريالصفوف في الصفحة: 20 افتراضيًا، و100 كحد أقصى.

الطلب

curl -s "http://localhost:3000/api/screener?profitableOnly=1&pageSize=5"

نموذج الاستجابة

200application/json

{
  "data": {
    "rows": [
      {
        "symbol": "NWRB",
        "name": "Northwind Robotics",
        "exchange": "NASDAQ",
        "sector": "Technology",
        "industry": "Industrial Automation",
        "price": 733.8,
        "change": -16.52,
        "changePercent": -2.2,
        "previousClose": 750.32,
        "open": 750.03,
        "dayHigh": 751.29,
        "dayLow": 731.5,
        "volume": 3471317,
        "avgVolume": 2962633,
        "marketCap": 982258754565,
        "peRatio": 60.35,
        "eps": 12.16,
        "dividendYield": null,
        "week52High": 963.99,
        "week52Low": 583.89,
        "afterHoursPrice": 731,
        "afterHoursChangePercent": -0.38,
        "updatedAt": "2026-11-12T21:00:00.000Z"
      }
    ],
    "total": 17,
    "page": 1,
    "pageSize": 5
  },
  "meta": {
    "provider": "demo",
    "generatedAt": "2026-11-12T21:00:04.512Z",
    "disclaimer": "Demo dataset: fictional issuers and simulated prices. Not investment advice.",
    "total": 17,
    "page": 1,
    "pageSize": 5
  }
}

تم اختصار النموذج إلى صف واحد.

المصادقة

لا يتطلب الوضع التجريبي أي مفتاح. وعندما يضبط الخادم متغير البيئة API_KEY، يجب أن يرسل كل طلب القيمة نفسها في ترويسة X-API-Key؛ وأي قيمة أخرى تستقبل 401 unauthorized.

curl -s "http://localhost:3000/api/quotes/NWRB" \
  -H "X-API-Key: your-key-here"
ملاحظة
يُقرأ المفتاح على الخادم فقط. وتستدعي أزرار إرسال الطلب في هذه الصفحة واجهة API من متصفحك دون مفتاح، لذا تعيد 401 ما دامت مصادقة المفتاح مُفعّلة.

رموز الأخطاء

تعيد الطلبات الفاشلة حالة HTTP مطابقة وكائن خطأ واحدًا. اعتمد على code؛ أما message فهو مكتوب للبشر وقد يتغير.

{
  "error": {
    "code": "not_found",
    "message": "A human-readable explanation."
  }
}
حالة HTTPالرمزمتى يحدث
400bad_requestقيمة معامل غير مسموح بها، مثل نطاق شموع غير معروف.
401unauthorizedتم ضبط API_KEY والطلب لا يحمل ترويسة X-API-Key مطابقة.
404not_foundالرمز غير موجود في مجموعة البيانات.
405method_not_allowedواجهة API للقراءة فقط: /api/quotes يجيب على POST بهذا الرمز.
429rate_limitedأكثر من 60 طلب في 60 ثانية من عنوان IP واحد إلى نقطة نهاية واحدة. وتتضمن الاستجابة Retry-After بالثواني.

شاهد البيانات نفسها داخل المنتج

تقرأ نظرة عامة على السوق وصفحات عروض الأسعار والفحص المزود نفسه الذي تقرأه هذه النقاط.