Criação de consultas avançadas

Ao trabalhar com a API do finlight.me, você tem o poder de obter exatamente os dados de que precisa por meio de técnicas de criação de consultas avançadas. Este guia apresenta métodos complexos de filtragem, ordenação e paginação para ajudar você a otimizar seu processo de obtenção de dados.

Acesse a API rapidamente e teste suas consultas usando nosso Painel - Testador de API.

Idioma e cobertura multilíngue

O finlight indexa notícias em muitos idiomas, mas cada requisição é filtrada para um idioma. O parâmetro language tem como padrão en, portanto, se você não o definir, recebe apenas artigos em inglês — o conteúdo em qualquer outro idioma é excluído silenciosamente.

Importante: language tem como padrão en. Uma requisição sem language retorna apenas resultados em inglês. Artigos publicados em outros idiomas (por exemplo, muitos veículos em chinês, zh) não são retornados, a menos que você solicite explicitamente esse idioma.

Como funciona

• No nível do artigo, correspondência exata. language filtra pelo código ISO 639-1 de cada artigo como correspondência exata. language=en retorna apenas artigos en e nunca de, zh, etc.
• Um idioma por requisição. language aceita um único valor — arrays/listas separadas por vírgula não são suportados e não há opção de "todos os idiomas". Para cobrir vários idiomas, envie uma requisição por idioma e combine os resultados.
• As fontes podem ser multilíngues. Uma mesma fonte pode publicar em mais de um idioma; o filtro seleciona os artigos pelo idioma deles, não pela fonte. Os artigos não ingleses de um veículo só aparecem quando você solicita esse idioma.

Exemplos

Padrão (apenas inglês) — equivalente:

query=Alibaba
query=Alibaba&language=en

Cobertura em chinês:

query=Alibaba&language=zh

Cobrir inglês + chinês — duas requisições, depois combinar:

query=Alibaba&language=en
query=Alibaba&language=zh

Dica: Use códigos ISO 639-1 (en, de, fr, zh, …). O conjunto de fontes padrão do finlight abrange muitos idiomas — o inglês é apenas o filtro padrão, não o limite da cobertura.

Filtragem por consulta

O parâmetro query permite uma lógica flexível baseada em palavras-chave e precisão em nível de campo. Agora você pode mirar campos específicos como ticker, exchange, isin, source, openfigi e mais.

Uso básico de palavras-chave

Palavra-chave única:

query=Nvidia stock

Frase exata: Coloque as frases entre aspas duplas para buscar correspondências exatas.

query="Elon Musk"

Inclusão / Exclusão com operadores

Forçar inclusão (+) e exclusão (-):

Use + para exigir/incluir e - para excluir termos ou valores específicos de campo.

query=stock +market -google

Isso retornará artigos que contêm "stock" e "market", mas excluirá os que mencionam "google".

Filtragem em nível de campo

Observação: Este é um poderoso recurso novo que permite filtrar resultados com base em campos específicos diretamente dentro do parâmetro query.

Agora você pode consultar campos específicos diretamente usando a sintaxe field:value também no parâmetro query. Isso permite consultas mais precisas e complexas, possibilitando filtrar resultados com base em atributos específicos como símbolos de ticker, bolsas, ISINs, fontes e mais.

✨ Novo: Use o curinga * com os campos source, ticker e exchange para corresponder a todos os valores (ex.: source:*, ticker:*, exchange:*).

Campos suportados

• ticker (suporta o curinga *)

• isin

• title

• summary

• content

• openfigi

• exchange (suporta o curinga *)

  • Todas as bolsas seguem os padrões MIC (códigos de identificação de mercado). Os códigos suportados incluem: ASEX, BVCA, BVMF, DSMD, HSTC, XSTC, MISX, NEOE, PFTS, ROCO, XADS, XAMM, XAMS, XASX, XBAH, XBEL, XBEY, XBKK, XBOG, XBOM, XBOT, XBRA, XBRU, XBSE, XBUD, XBUE, XBUL, XCAS, XCNQ, XCOL, XCSE, XCYS, XDAR, XDFM, XDHA, XDUS, XETR, XFKA, XFRA, XGHA, XHAM, XHEL, XHKG, XICE, XIDX, XIST, XJAM, XJSE, XKAR, XKAZ, XKLS, XKOR, XKUW, XLIM, XLIS, XLIT, XLJS, XLUS, XLUX, XMAL, XMAU, XMEX, XMIL, XMSW, XMUN, XNAI, XNAM, XNAS, XNGM, XNGO, XNSA, XNSE, XNYS, XASE, XOSL, XPAR, XPHS, XPRA, XRIS, XSAP, XSAU, XSES, XSCA, XSGO, XSHE, XSHG, XKRX, XSTU, XSWX, XTAE, XTAI, XTAL, XTSE, XTSX, XTUN, XUBS, XUGA, XWAR, XWBO, XZAG, XZIM, XSTO, OTCM, BMEX, XDUB, XJPX, BCXE, XPAE, XLON, XMUS, XNZE, XCAI, XBRV

• country

  • Filtra pelo país da empresa usando códigos de país ISO 3166-1 alpha-2 (ex.: US, GB, DE, JP, CN, FR, CA, AU, IN, BR, etc.)

• category

  • Filtra por categoria de artigo. Valores possíveis: markets, economy, business, politics, geopolitics, regulation, technology, energy, commodities, crypto, health, climate, security

• source (suporta o curinga *)

  • Ver todas as fontes disponíveis na documentação da API

Suporte a curingas

O curinga * permite incluir explicitamente todas as fontes, tickers ou bolsas na sua consulta. Isso é particularmente útil quando você quer garantir uma cobertura ampla ou ao combinar com outros filtros.

Exemplos:

query=source:*

Retorna artigos de todas as fontes disponíveis.

query=ticker:* country:US

Retorna artigos sobre qualquer ticker de empresas dos EUA.

query=exchange:* -crypto

Retorna artigos de todas as bolsas, excluindo o conteúdo de criptomoedas.

Exemplos de filtros de campo

Experimente no Testador de API para ver como funciona e criar facilmente suas próprias consultas complexas.

Filtrar por fonte exata:

query=source:www.some-source.de

Excluir uma fonte:

query=-source:www.some-source.de

Exigir um ticker específico e excluir alguma fonte:

query=ticker:AAPL -source:www.some-source.de

Encontrar resultados em que o conteúdo mencione "earnings" e a bolsa seja NASDAQ:

query=content:earnings exchange:nasdaq

Filtrar por empresas de um país específico:

query=country:US

Encontrar notícias sobre empresas alemãs, excluindo Schulden:

query=country:DE -Schulden

Combinar filtragem por país e ticker:

query=country:US ticker:NVD

Combinar filtragem de campo com busca geral:

query="quarterly report" source:www.some-source.com -crypto

Operadores booleanos

Observação: As palavras são unidas por padrão com AND; você não precisa usar AND explicitamente, a menos que queira combinar com OR ou NOT.

A lógica AND / OR / NOT é totalmente suportada:

query=stock AND google
query=amazon OR google
query=market AND NOT bitcoin

Use parênteses para agrupar: Combine expressões lógicas para uma filtragem avançada.

query=("Elon Musk") AND (twitter OR tesla)

Combine com curingas para consultas poderosas:

query=ticker:* AND (country:US OR country:GB) -crypto
query=source:* exchange:XNAS

💡 Dicas para usuários avançados

• Os filtros de campo suportam + e - para valores exigidos e excluídos.
• O curinga * pode ser usado com os campos source, ticker e exchange para corresponder a todos os valores.
• Você pode combinar vários campos e palavras-chave para consultas altamente direcionadas.
• Operadores booleanos como AND, OR e NOT não diferenciam maiúsculas de minúsculas.
• Os parênteses () ajudam a controlar a precedência em consultas complexas.
• Use aspas duplas " em torno de frases de várias palavras para evitar correspondências parciais.

Conclusão - Combine tudo

Exemplo: Quer notícias sobre a Tesla (ticker:TSLA), de fontes confiáveis, que não sejam sobre cripto?

query=+ticker:TSLA -crypto AND (+source:www.bloomberg.com OR +source:www.reuters.com)

Exemplo: Quer notícias sobre a Tesla (ticker:TSLA) ou a Apple (ticker:AAPL) da Bloomberg?

query=source:www.bloomberg.com AND ticker:TSLA OR source:www.bloomberg.com AND ticker:APPL

Exemplo: Quer notícias sobre empresas dos EUA listadas na NASDAQ, excluindo o conteúdo de criptomoedas?

query=country:US exchange:XNAS -crypto

Exemplo: Quer notícias sobre empresas de tecnologia europeias (Alemanha, França ou Reino Unido) com menções de resultados?

query=earnings AND (country:DE OR country:FR OR country:GB)

Exemplo: Quer todas as notícias relacionadas a tickers de todas as fontes, excluindo cripto?

query=ticker:* source:* -crypto

Experimente no Testador de API para ver como funciona e criar facilmente suas próprias consultas complexas.

Campos de consulta do Raw WebSocket

O Raw WebSocket suporta um subconjunto de filtros em nível de campo adaptados ao seu modelo de dados simplificado. Diferentemente do WebSocket enriquecido e da API REST, o Raw WebSocket não suporta filtros de campo relacionados a ticker, bolsa ou empresa.

Campos suportados

• source - Filtra pelo domínio de origem do artigo
• title - Filtra pelo conteúdo do título do artigo
• summary - Filtra pelo conteúdo do resumo do artigo

Exemplos

Filtrar por conteúdo do título:

query=title:Nvidia

Combinar filtros de título e resumo:

query=summary:earnings +title:Tesla

Filtrar por fonte com exclusão de palavra-chave:

query=source:www.reuters.com -crypto

Combinar vários filtros de campo com operadores booleanos:

query=title:Apple AND summary:revenue

Observação: Os operadores de consulta padrão (+, -, AND, OR, NOT, parênteses e aspas duplas) funcionam todos com os filtros de campo do Raw WebSocket.

Precisa de ajuda?

Se você se sentir travado, tiver uma dúvida ou ver espaço para melhorias, não hesite em entrar em contato. Aguardamos seu contato e queremos apoiar o seu sucesso com a API do finlight.me.