Filtragem Avançada: Consultas Precisas com a API da finlight

Um feed de notícias amplo é ruído. O valor está em obter exatamente as matérias que importam para você. A finlight oferece duas maneiras de fazer isso, e elas funcionam em conjunto:

1. Filtros estruturados para os casos comuns (tickers, países, categorias, fontes, datas).
2. Uma linguagem de consulta no campo query para lógica booleana e busca em texto completo.

Este guia cobre ambos, usando POST /v2/articles. Se você ainda não fez sua primeira chamada, comece pelo Guia de Início Rápido.

Filtros estruturados

Estes são os parâmetros que você usará com mais frequência:

• tickers — empresas, ex.: ["AAPL", "NVDA"]
• countries — códigos ISO 3166-1 alpha-2, ex.: ["US", "GB"]
• categories — uma ou mais das 13 categorias, ex.: ["markets", "regulation"]
• sources / excludeSources / optInSources — incluir, excluir ou optar por veículos específicos
• from / to — intervalo de datas, YYYY-MM-DD ou ISO 8601
• order (ASC / DESC) e orderBy (publishDate, createdAt, revisedDate)

Uma requisição estruturada simples:

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
  }'

A linguagem de consulta

Quando você precisa de lógica booleana ou correspondência de texto, use o campo query. Ele suporta filtros por campo, operadores booleanos, agrupamento, frases exatas e curingas.

Campos suportados

Operadores

• AND / OR / NOT para combinar termos.
• Parênteses ( ) para agrupar, ex.: (ticker:AAPL OR ticker:NVDA).
• Aspas " " para uma frase exata, ex.: "interest rates".
• Curingas * em ticker, source e exchange, ex.: ticker:BRK*.
• + / - para exigir ou excluir um termo, ex.: +ticker:AAPL -category:crypto.

Juntando tudo

Encontre matérias de resultados sobre Apple ou Nvidia, mas não de uma fonte específica:

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

Os filtros estruturados e a string de consulta são combinados (com AND entre eles), então você pode misturá-los. Por exemplo, envie query para a lógica booleana e categories / from como filtros estruturados:

// 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)

Paginação e histórico profundo

Use page e pageSize (até 100 por página) para percorrer os resultados. Há uma regra a saber: o deslocamento (page * pageSize) tem limite de 10.000. Para ir mais fundo no histórico, não continue aumentando o page; em vez disso, estreite a janela com from e to e pagine dentro de cada janela. Isso mantém as consultas rápidas e permite percorrer qualquer extensão de histórico.

Para onde ir agora

• Tickers e Bolsas do Jeito Certo — filtre com precisão para empresas com listagem dupla.
• Notícias Globais por País e Categoria.
• Documentação completa.

Obtenha sua chave de API gratuita →