التصفية المتقدمة: استعلامات دقيقة باستخدام finlight API

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

1. المرشّحات المهيكلة للحالات الشائعة (رموز الأسهم، الدول، الفئات، المصادر، التواريخ).
2. لغة استعلام في الحقل query للمنطق البولياني والمطابقة النصية الكاملة.

يغطي هذا الدليل الطريقتين باستخدام POST /v2/articles. وإن لم تكن قد أجريت أول استدعاء بعد، فابدأ من دليل البدء السريع.

المرشّحات المهيكلة

هذه هي المعاملات التي ستلجأ إليها أكثر من غيرها:

• tickers — الشركات، مثل ["AAPL", "NVDA"]
• countries — رموز ISO 3166-1 alpha-2، مثل ["US", "GB"]
• categories — واحدة أو أكثر من الفئات الثلاث عشرة، مثل ["markets", "regulation"]
• sources / excludeSources / optInSources — تضمين منافذ إعلامية محددة أو استبعادها أو إضافتها اختياريًا
• from / to — نطاق زمني، بصيغة YYYY-MM-DD أو ISO 8601
• order (ASC / DESC) وorderBy (publishDate، createdAt، revisedDate)

طلب مهيكل بسيط:

curl -X POST https://api.finlight.me/v2/articles \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tickers": ["AAPL", "NVDA"],
    "categories": ["markets"],
    "from": "2026-01-01",
    "pageSize": 50
  }'

لغة الاستعلام

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

الحقول المدعومة

المعاملات

• AND / OR / NOT لدمج المصطلحات.
• الأقواس ( ) للتجميع، مثل (ticker:AAPL OR ticker:NVDA).
• علامات الاقتباس " " للعبارة الدقيقة، مثل "interest rates".
• أحرف البدل * على ticker وsource وexchange، مثل ticker:BRK*.
• + / - لطلب مصطلح أو استبعاده، مثل +ticker:AAPL -category:crypto.

الجمع بينها

ابحث عن قصص الأرباح المتعلقة بـ Apple أو Nvidia، لكن ليس من مصدر محدد:

(ticker:AAPL OR ticker:NVDA) AND "earnings" AND NOT source:www.example.com

يُدمَج المرشّح المهيكل وسلسلة الاستعلام معًا (بربطهما بـ AND)، لذا يمكنك المزج بينهما. على سبيل المثال، أرسل query للمنطق البولياني وcategories / from كمرشّحات مهيكلة:

// TypeScript
import { FinlightApi } from 'finlight-client';

const client = new FinlightApi({ apiKey: 'YOUR_API_KEY' });

const response = await client.articles.fetchArticles({
  query: '(ticker:AAPL OR ticker:NVDA) AND "earnings"',
  categories: ['markets'],
  from: '2026-01-01',
  pageSize: 50,
});

# Python
from finlight_client import FinlightApi, ApiConfig
from finlight_client.models import GetArticlesParams

client = FinlightApi(config=ApiConfig(api_key="YOUR_API_KEY"))

params = GetArticlesParams(
    query='(ticker:AAPL OR ticker:NVDA) AND "earnings"',
    categories=["markets"],
    from_="2026-01-01",
    pageSize=50,
)
response = client.articles.fetch_articles(params)

ترقيم الصفحات والتاريخ العميق

استخدم page وpageSize (حتى 100 لكل صفحة) للتنقل بين النتائج. وهناك قاعدة واحدة عليك معرفتها: الإزاحة (page * pageSize) محدودة بسقف 10,000. وللتعمق أكثر في التاريخ، لا تواصل زيادة page، بل ضيّق النافذة الزمنية بـ from وto وتنقّل ضمن كل نافذة. هذا يبقي الاستعلامات سريعة ويتيح لك المرور عبر أي قدر من التاريخ.

إلى أين تذهب بعد ذلك

• استخدام رموز الأسهم والبورصات على نحو صحيح — تصفية دقيقة للشركات المدرجة في أكثر من بورصة.
• الأخبار العالمية حسب الدولة والفئة.
• التوثيق الكامل.

احصل على مفتاح API المجاني ←