Home › API documentation › GET /v1/trends/keywords

GET /v1/trends/keywords

Which words are holding the news together at this moment, and in how many countries at once.

bash

curl "https://freenewsapi.ai/v1/trends/keywords?size=5&min_trends=10"

Where the words come from

They are not extracted from text by frequency. When the model groups articles into a story it names the two to four rare words that tell that story from every other — a surname, a city, a brand. Those words are what you get here. That is why the list reads like a set of events rather than a set of stopwords.

Parameters

countryISO-2, comma separated

Words used in these countries only. Omit for the whole world.

categorystring, comma separated

Same categories as /v1/trends.

window / date / since / untilsee /docs/trendsdefault 24h

The period, exactly as in the trends endpoint.

startsstring

Prefix filter: starts=dro finds drone, drones, dron. Useful for languages where the same root arrives in several forms.

min_trendsintdefault 2

A word used by a single story is not a theme, it is a label. Raise this to 10 or 20 to see only what several stories share.

size / offsetintdefault 50 / 0

Up to 500 words per call.

The countries column is the interesting one

Each word comes with countries — in how many national presses it appears at the same time. A word with 70 countries is a global event; a word with one is domestic, however loud. This is the cheapest way we know to separate the two.

Reading the numbers

trends counts stories in the window. articles_total counts articles of those stories over their whole life, not just inside the window — computing it per window meant touching the article table and cost 3.6 seconds against 0.4. The story counts agree to within single units either way, so the trade was worth it, but the field is named to say what it is.

Feeding it back

The words come back in a form /v1/trends accepts directly:

bash

curl "https://freenewsapi.ai/v1/trends?kw=drone&country=UA&headlines=2"