مرجع 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 في كل استجابة المصدر الذي أجاب.قائمة عروض الأسعار
/api/quotesيعيد صفحة واحدة من الأدوات كمصفوفة مسطحة، مع total و page و pageSize داخل meta. وكل مرشح من مرشحات الفحص أدناه يعمل هنا أيضًا؛ وتُهمل القيم التي يتعذر تحليلها.
المعاملات
| المعامل | الموقع | النوع | مطلوب | الوصف |
|---|---|---|---|---|
| sector | query | string | اختياري | اسم القطاع بدقة: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate. |
| sort | query | string | اختياري | حقل الترتيب: marketCap (الافتراضي)، price، changePercent، volume أو symbol. |
| order | query | string | اختياري | اتجاه الترتيب: desc (الافتراضي) أو asc. |
| page | query | number | اختياري | رقم الصفحة، بدءًا من 1. |
| pageSize | query | number | اختياري | الصفوف في الصفحة: 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
}
}تم اختصار النموذج إلى صف واحد.
الحصول على عرض سعر
/api/quotes/{symbol}يعيد عرض السعر الكامل لأداة أو مؤشر واحد. ويعيد الرمز غير المعروف 404 not_found.
المعاملات
| المعامل | الموقع | النوع | مطلوب | الوصف |
|---|---|---|---|---|
| symbol | path | string | مطلوب | رمز الأداة أو المؤشر، مثل 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."
}
}الحصول على الشموع
/api/candles/{symbol}يعيد شموع OHLCV من الأقدم إلى الأحدث. ويستخدم النطاق 1D فواصل زمنية من 30 دقيقة، بينما تستخدم بقية النطاقات شموعًا يومية. ويعيد النطاق غير المعروف 400 bad_request.
المعاملات
| المعامل | الموقع | النوع | مطلوب | الوصف |
|---|---|---|---|---|
| symbol | path | string | مطلوب | رمز الأداة أو المؤشر، مثل NWRB. والمطابقة تتجاهل حالة الأحرف. |
| range | query | string | اختياري | واحد من 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.
فحص الأدوات
/api/screenerيفلتر الأدوات ويرتبها ويقسّمها إلى صفحات بالمعاملات نفسها المستخدمة في صفحة الفحص. وتحتوي النتيجة على rows مع total و page و pageSize؛ وتُهمل القيم التي يتعذر تحليلها.
المعاملات
| المعامل | الموقع | النوع | مطلوب | الوصف |
|---|---|---|---|---|
| sector | query | string | اختياري | اسم القطاع بدقة: Technology, Healthcare, Financials, Consumer Discretionary, Consumer Staples, Industrials, Energy, Materials, Utilities, Real Estate. |
| minMarketCap, maxMarketCap | query | number | اختياري | حدود القيمة السوقية بالدولار USD. |
| minPrice, maxPrice | query | number | اختياري | حدود السعر بالدولار USD. |
| minChangePercent, maxChangePercent | query | number | اختياري | حدود التغير اليومي بالنقاط المئوية: -3 تعني -3%. |
| minVolume | query | number | اختياري | الحد الأدنى لحجم التداول اليومي بالأسهم. |
| profitableOnly | query | string | اختياري | اضبطه على 1 للإبقاء فقط على الأدوات التي يزيد فيها EPS على 0. |
| sort | query | string | اختياري | حقل الترتيب: marketCap (الافتراضي)، price، changePercent، volume أو symbol. |
| order | query | string | اختياري | اتجاه الترتيب: desc (الافتراضي) أو asc. |
| page | query | number | اختياري | رقم الصفحة، بدءًا من 1. |
| pageSize | query | number | اختياري | الصفوف في الصفحة: 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"رموز الأخطاء
تعيد الطلبات الفاشلة حالة HTTP مطابقة وكائن خطأ واحدًا. اعتمد على code؛ أما message فهو مكتوب للبشر وقد يتغير.
{
"error": {
"code": "not_found",
"message": "A human-readable explanation."
}
}| حالة HTTP | الرمز | متى يحدث |
|---|---|---|
| 400 | bad_request | قيمة معامل غير مسموح بها، مثل نطاق شموع غير معروف. |
| 401 | unauthorized | تم ضبط API_KEY والطلب لا يحمل ترويسة X-API-Key مطابقة. |
| 404 | not_found | الرمز غير موجود في مجموعة البيانات. |
| 405 | method_not_allowed | واجهة API للقراءة فقط: /api/quotes يجيب على POST بهذا الرمز. |
| 429 | rate_limited | أكثر من 60 طلب في 60 ثانية من عنوان IP واحد إلى نقطة نهاية واحدة. وتتضمن الاستجابة Retry-After بالثواني. |
شاهد البيانات نفسها داخل المنتج
تقرأ نظرة عامة على السوق وصفحات عروض الأسعار والفحص المزود نفسه الذي تقرأه هذه النقاط.