Продвинутая фильтрация: точные запросы через finlight API

Широкий новостной поток — это шум. Ценность в том, чтобы получать именно те материалы, которые вам важны. finlight даёт для этого два способа, и они работают вместе:

1. Структурированные фильтры для типичных случаев (тикеры, страны, категории, источники, даты).
2. Язык запросов в поле query для булевой логики и полнотекстового поиска.

Это руководство охватывает оба способа на примере POST /v2/articles. Если вы ещё не делали первый вызов, начните с руководства по быстрому старту.

Структурированные фильтры

Это параметры, к которым вы будете обращаться чаще всего:

• tickers — компании, например ["AAPL", "NVDA"]
• countries — коды ISO 3166-1 alpha-2, например ["US", "GB"]
• categories — одна или несколько из 13 категорий, например ["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-ключ →