Advanced Query Building

When working with the finlight.me API, you have the power to retrieve exactly the data you need through advanced query building techniques. This guide walks you through complex filtering, sorting, and pagination methods to help you optimize your data retrieval process.

Quickly access the API and test your queries using our Dashboard - API Tester.

Language and Multilingual Coverage

finlight indexes news in many languages, but every request is filtered to one language. The language parameter defaults to en, so if you don't set it you receive English articles only — content in any other language is silently excluded.

Important: language defaults to en. A request without language returns only English results. Articles published in other languages (for example many Chinese-language outlets, zh) are not returned unless you explicitly request that language.

How it works

  • Article-level, exact match. language filters on each article's ISO 639-1 code as an exact match. language=en returns only en articles and never de, zh, etc.
  • One language per request. language takes a single value — arrays/comma lists are not supported and there is no "all languages" option. To cover several languages, send one request per language and merge the results.
  • Sources can be multilingual. A single source may publish in more than one language; the filter selects articles by their language, not the source. An outlet's non-English articles only appear when you request that language.

Examples

Default (English only) — equivalent:

query=Alibaba
query=Alibaba&language=en

Chinese-language coverage:

query=Alibaba&language=zh

Cover English + Chinese — two requests, then merge:

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

Tip: Use ISO 639-1 codes (en, de, fr, zh, …). finlight's default source set spans many languages — English is just the default filter, not the limit of coverage.

Query Filtering

The query parameter enables flexible keyword-based logic and field-level precision. You can now target specific fields like ticker, exchange, isin, source, openfigi and more.

Basic Keyword Usage

Single keyword:

query=Nvidia stock

Exact phrase: Wrap phrases in double quotes to search for exact matches.

query="Elon Musk"

Inclusion / Exclusion with Operators

Force inclusion (+) and exclusion (-):

Use + to require/inclusion, and - to exclude terms or field-specific values.

query=stock +market -google

This will return articles that contain "stock" and "market", but exclude any that mention "google".

Field-Level Filtering

Note: This is a powerful new feature that allows you to filter results based on specific fields directly within the query parameter.

You can now query specific fields directly using the field:value syntax also on the query parameter. This allows for more precise and complex queries, enabling you to filter results based on specific attributes like ticker symbols, exchanges, ISINs, sources, and more.

✨ New: Use wildcard * with source, ticker, and exchange fields to match all values (e.g., source:*, ticker:*, exchange:*).

Supported Fields

  • ticker (supports wildcard *)

  • isin

  • title

  • summary

  • content

  • openfigi

  • exchange (supports wildcard *)

    • All exchanges are MIC (Market identifier codes) standards. Supported codes include: 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

    • Filter by company country using ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE, JP, CN, FR, CA, AU, IN, BR, etc.)

  • category

    • Filter by article category. Possible values: markets, economy, business, politics, geopolitics, regulation, technology, energy, commodities, crypto, health, climate, security

  • source (supports wildcard *)

Wildcard Support

The wildcard * allows you to explicitly include all sources, tickers, or exchanges in your query. This is particularly useful when you want to ensure broad coverage or when combining with other filters.

Examples:

query=source:*

Returns articles from all available sources.

query=ticker:* country:US

Returns articles about any ticker for US companies.

query=exchange:* -crypto

Returns articles from all exchanges, excluding cryptocurrency content.

Field Filter Examples

Try it out in the API Tester to see how it works and create your own complex queries easily.

Filter by exact source:

query=source:www.some-source.de

Exclude a source:

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

Require specific ticker and exclude some source:

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

Find results where content mentions "earnings" and the exchange is NASDAQ:

query=content:earnings exchange:nasdaq

Filter by companies from a specific country:

query=country:US

Find news about German companies, excluding Schulden:

query=country:DE -Schulden

Combine country and ticker filtering:

query=country:US ticker:NVD

Combine field filtering with general search:

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

Boolean Operators

Note: Words are by default AND joined, you dont need to use AND explicitly unless you want to combine with OR or NOT.

AND / OR / NOT logic is fully supported:

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

Use parentheses for grouping: Combine logical expressions for advanced filtering.

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

Combine with wildcards for powerful queries:

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

💡 Tips for Power Users

  • Field filters support + and - for required and excluded values.
  • Wildcard * can be used with source, ticker, and exchange fields to match all values.
  • You can combine multiple fields and keywords for highly targeted queries.
  • Boolean operators like AND, OR, and NOT are case-insensitive.
  • Parentheses () help control precedence in complex queries.
  • Use double quotes " around multi-word phrases to avoid partial matches.

Conclusion - Combine Everything

Example: Want news about Tesla (ticker:TSLA), from trusted sources, not about crypto?

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

Example: Want news about Tesla (ticker:TSLA) or Apple (ticker:AAPL) from Bloomberg?

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

Example: Want news about US companies listed on NASDAQ, excluding cryptocurrency content?

query=country:US exchange:XNAS -crypto

Example: Want news about European tech companies (Germany, France, or UK) with earnings mentions?

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

Example: Want all ticker-related news from all sources, excluding crypto?

query=ticker:* source:* -crypto

Try it out in the API Tester to see how it works and create your own complex queries easily.

Raw WebSocket Query Fields

The Raw WebSocket supports a subset of field-level filters tailored to its simplified data model. Unlike the Enhanced WebSocket and REST API, the Raw WebSocket does not support ticker, exchange, or company-related field filters.

Supported Fields

  • source - Filter by article source domain
  • title - Filter by article title content
  • summary - Filter by article summary content

Examples

Filter by title content:

query=title:Nvidia

Combine title and summary filters:

query=summary:earnings +title:Tesla

Filter by source with keyword exclusion:

query=source:www.reuters.com -crypto

Combine multiple field filters with boolean operators:

query=title:Apple AND summary:revenue

Note: The standard query operators (+, -, AND, OR, NOT, parentheses, and double quotes) all work with Raw WebSocket field filters.

Need Help?

If you ever feel stuck, have a question, or see room for improvement, don’t hesitate to reach out. We look forward to hearing from you and supporting your success with the finlight.me API.