نقاط النهاية

في هذه الصفحة، سنتعمّق في نقاط النهاية المختلفة التي يمكنك استخدامها لاسترجاع مقالات الأخبار المالية برمجياً. سننظر في كيفية الاستعلام عن المقالات باستخدام واجهة finlight.me API.

نموذج المقال

يحتوي نموذج المقال في الاستجابة على جميع المعلومات المتعلقة بالمقال، مثل الرابط والعنوان وتاريخ النشر والمصدر. كما يحتوي على المشاعر ومستوى الثقة فيها.

Name
link
Type
string
Description
رابط URL للمقال الكامل.
Name
source
Type
string
Description
موقع المصدر الإلكتروني. مثال: www.reuters.com
Name
title
Type
string
Description
عنوان المقال.
Name
summary
Type
string
Description
ملخص المقال إن وُجد. يمكن أن يكون فارغاً (null).
Name
publishDate
Type
Date
Description
تاريخ النشر بصيغة تاريخ ISO.
Name
createdAt
Type
Date
Description
التاريخ الذي فُهرس فيه المقال لأول مرة بواسطة نظام finlight، كسلسلة تاريخ ISO 8601.
Name
revisedDate
Type
Date | null
Description
تاريخ آخر مراجعة للمقال بعد النشر الأولي، كسلسلة تاريخ ISO 8601. null عندما لم تتم مراجعة المقال مطلقاً. يُرجَع عند استخدام orderBy=revisedDate أو عند تفعيل includeUpdates عبر WebSocket/Webhook.
Name
isUpdate
Type
boolean
Description
true عندما تكون حمولة المقال هذه إعادة تسليم نتجت عن مراجعة بعد النشر. موجودة فقط عند تفعيل includeUpdates في اشتراك WebSocket أو Webhook.
Name
language
Type
string
Description
رمز اللغة بصيغة ISO 639-1. مثال: en | de | fr
Name
sentiment
Type
string
Description
نتيجة تحليل المشاعر. يمكن أن تكون القيم positive | neutral |negative
Name
confidence
Type
number
Description
مستوى الثقة في تحليل المشاعر من 0 إلى 1.
Name
images
Type
string[]
Description
مصفوفة من روابط URL للصور من المقال.
Name
countries
Type
string[]
Description
مصفوفة من رموز الدول بصيغة ISO 3166-1 alpha-2 تمثّل الدول المرتبطة بالمقال. مثال: ["US", "GB", "DE"]. يمكن أن تكون فارغة.
Name
categories
Type
string[]
Description
مصفوفة من فئات المقال. القيم الممكنة: markets | economy | business | politics | geopolitics | regulation | technology | energy | commodities | crypto | health | climate | security. يمكن أن تكون فارغة.
Name
companies
Type
Company[]
Description
مصفوفة من الشركات المذكورة في المقال. تُعرض/متاحة فقط مع مستوى اشتراك محدد. يمكن أن تكون فارغة (null).

نموذج الشركة

يحتوي نموذج الشركة في الاستجابة على معلومات حول شركة مذكورة في مقال. ويشمل تفاصيل مثل اسم الشركة ورمز السهم والصناعة وغيرها.

Name
companyId
Type
number
Description
المعرّف الفريد للشركة.
Name
confidence
Type
string
Description
مستوى الثقة في تحديد الشركة من 0 إلى 1.
Name
country
Type
string
Description
الدولة التي تتخذها الشركة مقراً بصيغة ISO 3166-1 alpha-2. مثال: US | DE | GB
Name
exchange
Type
string
Description
البورصة التي تُدرَج فيها الشركة.
Name
industry
Type
Date
Description
القطاع الصناعي للشركة. مثال: Biotechnology, Technology
Name
name
Type
string
Description
الاسم الكامل للشركة. مثال: Apple Inc.
Name
sector
Type
string
Description
قطاع الشركة. مثال: Technology | Health Care
Name
ticker
Type
string
Description
رمز السهم للشركة. مثال: AAPL | GOOGL
Name
isin
Type
string
Description
رقم التعريف الدولي للأوراق المالية (ISIN) للشركة. مثال: US0378331005
Name
openfigi
Type
string
Description
معرّف OpenFIGI للشركة. مثال: BBG000B9XRY4
Name
primaryListing
Type
object
Description
معلومات الإدراج في البورصة الرئيسية للشركة.
Name
primaryListing.ticker
Type
string
Description
رمز السهم الأساسي في البورصة الرئيسية.
Name
primaryListing.exchangeCode
Type
string
Description
رمز البورصة الرئيسية التي يُدرَج فيها السهم.
Name
primaryListing.exchangeCountry
Type
string
Description
دولة البورصة الرئيسية التي يُدرَج فيها السهم.
Name
isins
Type
string[]
Description
مصفوفة من أرقام التعريف الدولية للأوراق المالية (ISINs) للشركة.
Name
otherListings
Type
object[]
Description
مصفوفة من إدراجات البورصات الأخرى للشركة.
Name
otherListings[].ticker
Type
string
Description
رمز السهم في البورصة البديلة.
Name
otherListings[].exchangeCode
Type
string
Description
رمز البورصة البديلة التي يُدرَج فيها السهم.
Name
otherListings[].exchangeCountry
Type
string
Description
دولة البورصة البديلة التي يُدرَج فيها السهم.

POST/v2/articles

جلب المقالات

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

معاملات BODY الاختيارية

بما أن نقطة النهاية هذه تستخدم طلب POST، يمكنك تمرير المعاملات في نص الطلب. يتيح ذلك استعلامات وخيارات تصفية أكثر تعقيداً.

Name
query
Type
string
Description
استعلام بحث للعثور على مقالات ذات صلة باستخدام مرشّحات بسيطة أو متقدمة. الاستعلامات المتقدمة
Name
sources
Type
string[]
Description
مرشّح بسيط لمصدر واحد أو عدة مصادر (مصفوفة سلاسل نصية). راجع نقطة نهاية "الحصول على جميع المصادر" للقيم الصالحة. يدعم العلامة النائبة "*" لتضمين جميع المصادر.
Name
excludeSources[]
Type
string[]
Description
يستبعد مصدراً واحداً أو عدة مصادر (مصفوفة سلاسل نصية). راجع نقطة نهاية "الحصول على جميع المصادر" للقيم الصالحة.
Name
tickers
Type
string[]
Description
التصفية حسب رموز الأسهم (مصفوفة سلاسل نصية). سيُرجع هذا المقالات التي تذكر هذه الرموز. يدعم العلامة النائبة "*" لتضمين جميع رموز الأسهم.
Name
countries
Type
string[]
Description
التصفية حسب دولة الشركة باستخدام رموز الدول ISO 3166-1 alpha-2 (مصفوفة سلاسل نصية). مثال: ["US", "GB", "DE"]
Name
includeEntities
Type
boolean
Description
يتضمن الشركات المذكورة في المقال. يتطلب مستوى اشتراك محدداً.
Name
from
Type
string
Description
تاريخ البدء بصيغة YYYY-MM-DD أو سلسلة تاريخ ISO.
Name
to
Type
string
Description
تاريخ الانتهاء بصيغة YYYY-MM-DD أو سلسلة تاريخ ISO.
Name
language
Type
string
Description
التصفية حسب اللغة (ISO 639-1). القيمة الافتراضية هي en، التي تُرجع الإنجليزية فقط وتستبعد اللغات الأخرى — راجع اللغة والتغطية.
Name
orderBy
Type
string
Description
الترتيب حسب ("publishDate" أو "createdAt" أو "revisedDate") - الافتراضي "publishDate". publishDate هو تاريخ نشر المقال وفقاً للمصدر. createdAt هو وقت فهرسة المقال لأول مرة بواسطة finlight. revisedDate يرتّب حسب أحدث تاريخ مراجعة (المقالات التي لم تُراجَع مطلقاً تظهر في النهاية). ضع في اعتبارك أن بعض المصادر تنشر مقالات بتواريخ نشر سابقة.
Name
order
Type
string
Description
ترتيب الفرز ("ASC" أو "DESC") - الافتراضي "DESC".
Name
pageSize
Type
number
Description
عدد النتائج لكل صفحة (1-100).
Name
page
Type
number
Description
رقم الصفحة.

Request

GET

/v2/articles

curl -X POST 'https://api.finlight.me/v2/articles' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -d '{ "query": "Nvidia", "countries": ["US", "GB"] }'

Response

{
  "status": "ok",
  "page": 1,
  "pageSize": 20,
  "articles": [
    {
      "link": "https://www.example.com/article1",
      "source": "www.example.com",
      "title": "Stock Market Hits New Highs",
      "summary": "A brief summary of the article...",
      "publishDate": "2023-10-01T12:34:56Z",
      "language": "en",
      "sentiment": "positive",
      "confidence": 0.95,
      "images": [
                  "https://www.example.com/image1.jpg",
                  "https://www.example.com/image2.jpg"
                ],
      "countries": ["US"],
      "categories": ["markets", "technology"],
      "companies": [
                {
                    "companyId": 41494,
                    "confidence": "0.9335401058197021",
                    "country": "US",
                    "exchange": "XNAS",
                    "industry": "Biotechnology: Pharmaceutical Preparations",
                    "name": "Summit Therapeutics Inc. Common Stock",
                    "sector": "Health Care",
                    "ticker": "SMMT",
                    "isin": "US86627T1088",
                    "openfigi": "BBG01PH11VP5",
                    "primaryListing": {
                        "ticker": "SMMT",
                        "exchangeCode": "XNAS",
                        "exchangeCountry": "US"
                    },
                    "isins": ["US86627T1088", "US86627T2088"],
                    "otherListings": [
                        {
                            "ticker": "SMMT.L",
                            "exchangeCode": "XLON",
                            "exchangeCountry": "GB"
                        }
                    ]
                },
                ...
              ]
    },
    // ...
  ]
}

GET/v2/articles/by-link

جلب مقال عبر الرابط

استرجع مقالاً واحداً عبر رابط URL الخاص به. يُرجع بيانات المقال الكاملة مع تحليل المشاعر، ويتضمن اختيارياً المحتوى وكيانات الشركات.

معاملات الاستعلام المطلوبة

Name
link
Type
string
Description
رابط URL للمقال المراد جلبه.

معاملات الاستعلام الاختيارية

Name
includeContent
Type
boolean
Description
تضمين المحتوى الكامل للمقال في الاستجابة.
Name
includeEntities
Type
boolean
Description
تضمين الشركات المذكورة في المقال. يتطلب مستوى اشتراك محدداً.

Request

GET

/v2/articles/by-link

curl -X GET 'https://api.finlight.me/v2/articles/by-link?link=https%3A%2F%2Fwww.somepage.com%2Ftechnology%2Fexample-article&includeContent=true&includeEntities=true' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'

Response

{
  "status": "ok",
  "article": {
      "link": "https://www.somepage.com/technology/example-article",
      "source": "www.reuters.com",
      "title": "Nvidia Announces New GPU Architecture",
      "summary": "A brief summary of the article...",
      "publishDate": "2023-10-01T12:34:56Z",
      "createdAt": "2023-10-01T12:35:10Z",
      "language": "en",
      "sentiment": "positive",
      "confidence": 0.95,
      "content": "Full article content here...",
      "images": [
                  "https://www.example.com/image1.jpg"
                ],
      "countries": ["US"],
      "categories": ["technology"],
      "companies": [
                {
                    "companyId": 4157,
                    "confidence": "0.97",
                    "country": "US",
                    "exchange": "XNAS",
                    "industry": "Semiconductors",
                    "name": "NVIDIA Corporation",
                    "sector": "Technology",
                    "ticker": "NVDA",
                    "isin": "US67066G1040",
                    "openfigi": "BBG000BBJQV0"
                }
              ]
  }
}

GET/v2/sources

الحصول على جميع المصادر

استرجع قائمة بجميع مصادر المقالات المدعومة حالياً.

ملاحظة: تُستخرَج المصادر على أساس بذل أقصى جهد وقد تتغير في المستقبل.

الاستجابة

مصفوفة JSON من كائنات المصدر. مثال:

Name
array
Type
Source[]
Description
مصفوفة من مصادر الأخبار.

نموذج المصدر

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

Name
domain
Type
string
Description
نطاق موقع المصدر الإلكتروني.
Name
isDefaultSource
Type
boolean
Description
يشير إلى ما إذا كان هذا المصدر مصدراً افتراضياً لواجهة API.

Request

GET

/v2/sources

curl -X GET 'https://api.finlight.me/v2/sources' \
  -H 'X-API-KEY: YOUR_API_KEY'

Response

[
  {
    "domain": "www.yahoo.com",
    "isDefaultSource": true
  },
  {
    "domain": "seekingalpha.com",
    "isDefaultSource": true
  },
  // ...
]