GET /v1/trends
Not articles — stories. A robot groups what publishers write into events, and this endpoint hands you those events with the numbers behind them.
curl "https://freenewsapi.ai/v1/trends?country=UA&size=2"What a trend is here
A trend is an event covered by several different outlets. One publisher writing
about itself is not a story, and the robot will not create one: at least two independent
publishers must carry it. That rule is what makes publishers the most useful
number in the response — it is the count of newsrooms that independently thought the
thing was worth covering.
Stories are recomputed for every country every five minutes. Two passes do it: one attaches fresh articles to stories already known, the other looks for new stories. The first needs no model and finishes in nineteen seconds for all 120 countries; the second is the slow one and is why the interval is five minutes rather than one.
Choosing the period
Three ways to say it, and they are mutually exclusive:
24hA rolling window ending now: 15m, 30m, 1h, 3h, 6h, 12h, 24h, 7d, 30d.
Fifteen minutes is the shortest on purpose. The robots run more often than that, but a shorter window shows a handful of stories in even the busiest country and reads as if the world went quiet.
One calendar day in UTC instead of a rolling window.
Explicit bounds: since=2026-08-29T06:00:00Z&until=2026-08-29T09:00:00Z. Either may be omitted. The span may not exceed 90 days — that is how long the corpus keeps articles.
Filtering
country=DE,FR,PL. Up to twenty at once. Omit it and you get every country in one list, which is the right way to ask «what is the world talking about».
politics, business, markets, tech, sport, health, science, culture, crime, conflict, weather, society.
Keep only stories carrying these words. Several words mean all of them, not any: kw=trump,china is stories about both.
The words are the ones the model used to tell stories apart — names, places, brands. Ask /v1/trends/keywords what is available before guessing.
Substring of the story title. Blunt but useful when you know the wording.
1Drop stories that fewer than this many outlets carry. The single most effective noise filter: min_publishers=5 leaves only what a good part of a national press agreed to cover.
1Same idea by article count. Weaker than the one above, because one prolific outlet can inflate it on its own.
Ordering and paging
publisherspublishers — how many newsrooms carry it, the default and usually what you want. articles, newest, oldest, title.
501–200 stories.
0Up to 10 000.
3How many article headlines to attach to each story, 0–10. Set it to 0 when you only need the shape of the day — the response gets several times smaller.
A few real calls
What a whole country is talking about, only stories a lot of outlets confirm:
curl "https://freenewsapi.ai/v1/trends?country=DE&min_publishers=5&sort=publishers&headlines=0"Everything about one keyword, worldwide, with sources:
curl "https://freenewsapi.ai/v1/trends?kw=nepal&size=20&headlines=2"Conflict coverage in three countries over an explicit window:
curl "https://freenewsapi.ai/v1/trends?country=UA,PL,RO&category=conflict&since=2026-08-29T06:00:00Z&until=2026-08-29T12:00:00Z"Response
Every story carries country, category, slug,
articles, publishers, first_seen,
latest, a url to the human page, and the headlines you asked
for. The envelope repeats the filters you sent, so a stored response explains itself
months later.
What it will not do
It will not tell you a story is important. publishers counts outlets, and
outlets copy each other — a syndicated wire piece on forty sites looks like forty
newsrooms. Treat the number as coverage breadth, not significance.
It will not give you sentiment. Tone lives in the BTC vs news dataset for crypto only, and extending it to everything is a different job.
