Saturday, November 15, 2025
Unlocking the Real Power of finlight: Why Most Users Underuse the Query Engine
Most finlight users work with the API through simple request fields—`countries`, `sources`, `tickers`, `from`, `to`, and so on. These fields are easy to understand and great for basic use cases.
But there’s a pattern we’ve noticed:
many users think they’re exploring the full dataset, but in reality, they’re only scratching the surface.
Why?
Because they aren’t using finlight’s real engine—the advanced query field of `/v2/articles`.
This article explains:
- why simple fields often don’t give you the results you expect
- how the default source set can silently limit your output
- why the `query` field is dramatically more powerful
- how to combine logic like *OR*, *AND*, and grouping across multiple data dimensions
- how to build flexible, expressive searches that match real-world analysis needs
If you want finlight to feel like a market intelligence system rather than a typical news API, understanding the query DSL is the key.
1. The Silent Limiter: Default Source Set
If you send a simple request like:
```json
{ "countries": ["IN"] }
```
You will get news about India, but only from finlight’s default source set - which consists mainly of large global outlets such as Reuters, Bloomberg, WSJ, BBC, and others.
What you won’t get:
- Indian local outlets
- Indian-language publications
- regional business media
- India-exclusive reporting
Unless you explicitly override the source list, finlight uses the default set every time.
This is the #1 reason users don’t see the breadth of coverage they expect.
2. The Hidden Trap of the Simple Fields: Everything Is AND
The simple body fields (`countries`, `tickers`, `sources`, etc.) always combine with AND.
So this request:
```json
{
"sources": ["economictimes.indiatimes.com"],
"countries": ["IN"]
}
```
means:
“Give me articles from Economic Times AND tagged with India.”
Most users think they're saying:
> “Give me Indian news sources + news about India.”
But that combination isn’t possible with simple fields. You get the intersection, not the union - which produces a much narrower dataset.
Advanced analysis requires more flexibility than strict AND logic.
3. Enter the Advanced Query Field: Real Logical Control
The `query` field gives you a full search DSL where you can combine:
- OR
- AND
- NOT
- parentheses
- source filters
- country filters
- exchange filters
- ticker filter
- and more
This is where finlight becomes a powerful financial intelligence engine.
Example
> “Give me all Indian sources OR any article about India OR anything about companies listed on Indian exchanges.”
Using simple fields? Impossible.
Using the query DSL? Easy:
```json
{
"query": "(
source:economictimes.indiatimes.com OR
source:www.livemint.com OR
source:www.businesstoday.in OR
source:www.moneycontrol.com
)
OR country:IN
OR exchange:XNSE
OR exchange:XBOM"
}
```
You now get:
- local Indian media
- global outlets writing about India
- coverage tied to Indian-listed companies
- cross-border reporting
- event-driven global reactions
This captures everything relevant - not just the tiny sliver from the default source set.
4. The Key Behaviors Every User Should Know
A. Default sources are only overridden when you explicitly reference sources
Override happens only if:
- you include a `sources: [...]` array
- or the query contains any `source:` filter
- or you request `source:*`
Everything else keeps you within the default set.
B. Query gives you unions, intersections, and groups
The difference in expressive power is enormous.
Simple fields
→ Only AND logic
→ Good for strict filtering (e.g., “only US news in English from Reuters”).
Advanced query
→ AND + OR + parentheses
→ Good for real analysis (e.g., “US tech OR US-listed Chinese companies OR anything tagging NASDAQ”).
C. “country = IN” does NOT mean “Indian news source”
This is a common misconception.
- `country:IN` = articles about India
- `source:economictimes.indiatimes.com` = articles from an Indian publisher
Completely different concepts that users should combine intentionally.
D. You can always say “use all sources”
If you want finlight to search the full dataset:
```json
{ "sources": ["*"] }
```
or
```json
{ "query": "source:* AND country:IN" }
```
5. Why This Matters: The Real Value of finlight
Most users start by thinking of finlight as a “news filter API.”
Once they learn the query engine, they realize it’s more like:
- a discovery engine
- a geopolitical signal pipeline
- an early-warning system
- a financial event graph
- a cross-source narrative tracker
The difference is night and day.
The advanced query DSL lets analysts build searches that mimic real-world questions instead of simplistic filters.
It's the difference between:
“Give me Indian news.”
versus
“Give me everything happening in, around, or affecting India, across local, global, and market-driven signals.”
finlight was built for the latter.
6. Final Thought: The Query Field Unlocks the Entire Dataset
The simple fields you know from `/v2/articles` are meant for fast, beginner-friendly filtering.
But the real power - the flexibility, the expressiveness, the ability to model complex analytical questions - lives in the query DSL.
Once you start combining source conditions, country tags, exchange codes, tickers, and logical operators, finlight becomes much more than a news API.
It becomes a *market intelligence engine*.
If you want help translating a use case into a powerful query, we’re always happy to assist.