Geopolitical news API
If you track conflicts, sanctions and diplomacy, an article feed hands you the same development forty times. CLSTR returns geopolitical news as events and situations: one record per happening, how many outlets report it, and a dated history, as JSON over REST and MCP.
The problem: a conflict feed is mostly repetition
When a tanker is hit in a strait, wires, regional outlets and trade press all write it up within a day, in their own languages. A keyword feed returns each one as a row. You spend the morning merging duplicates and still cannot tell a new strike from the fourth retelling of last week's.
And the feed has no memory. It answers "what was published", not "how did this get here", so the context a brief needs is rebuilt by hand.
What an analyst needs
- The event, once, with linked sources and the count of outlets covering it.
- How widely it is reported: an outlet count per event.
- How it got here: related events in one storyline, with a dated timeline and a maintained summary.
- A filter by place and topic, so a regional desk sees its region.
How CLSTR answers it
CLSTR reads about 107,000 articles a day from about 20,000 sources a day, in 58 languages and from publishers in 176 countries, over the 30 days to October 21, 2026. Coverage of one happening becomes a cluster: deduplicated, with a source count and a significance score from 1 to 10 generated by an AI model. Related clusters link into a situation, whose timeline reaches back to where it started, even past your search window.
Filter with category=international or politics, and with country (ISO codes, comma-separated). Details on News API by country and News timeline API.
Worked example: one maritime situation
Search, then open the situation behind the top results.
curl -s "https://api.clstr.news/v1/search?q=Red%20Sea%20shipping&days=30" \ -H "Authorization: Bearer clstr_YOUR_KEY" curl -s "https://api.clstr.news/v1/situations/maritime-attacks-in-the-strait-of-hormuz?timeline_limit=30" \ -H "Authorization: Bearer clstr_YOUR_KEY"
Over MCP, as tools/call params:
{ "name": "search_situations",
"arguments": { "query": "Red Sea shipping", "days": 30 } }
{ "name": "get_situation_timeline",
"arguments": { "situation_id": "maritime-attacks-in-the-strait-of-hormuz", "timeline_limit": 30 } }
On a Free key the search answered with "days": 7: a window wider than the tier allows is clamped, not rejected. Because search matches meaning, it returned events from the Red Sea, the Strait of Hormuz and the Black Sea, each under its situation.
Captured 2026-10-28 via get_situation_timeline, newest first (trimmed to five of 23 entries). Titles are generated from the coverage; any figure inside one is what the sources reported.
{
"title": "Escalating maritime attacks and economic impact in Hormuz",
"cluster_count": 23,
"source_count": 511,
"first_seen": "2026-09-02T08:43:36.000Z",
"timeline": [
{ "published_at": "2026-10-27T17:13:48.000Z", "sources": 2,
"title": "Strait of Hormuz sees record shipping attacks amid Iran tensions" },
{ "published_at": "2026-10-15T08:41:25.000Z", "sources": 156,
"title": "Oil prices surge as Middle East tensions and tanker attacks drive Brent above $110" },
{ "published_at": "2026-10-14T13:42:36.000Z", "sources": 62,
"title": "Strait of Hormuz shipping attacks cause two vessels to sink" },
{ "published_at": "2026-10-10T19:01:00.000Z", "sources": 76,
"title": "Strait of Hormuz: IRGC reports third supertanker hit by mine" },
{ "published_at": "2026-09-02T08:43:36.000Z", "sources": 49,
"title": "Saudi tanker Sidr attacked in Strait of Hormuz, killing two sailors" }
]
}
Read the arc from dates and counts: one attack on 2 September, carried by 49 outlets; a run of strikes in mid-October, 60 to 160 each; and the newest event, two outlets so far. A low count on a new event says how many had covered it yet, not that it matters less. One entry reports that accounts conflict on whether projectiles or mines sank the two vessels. CLSTR carries both accounts.
If this situation is gone when you read this, run the same search and open whichever situation the top results name.
A weekly brief in three calls
GET /situations?category=international&country=IR,SA,YE&days=7(get_top_situations,window: "7d"): what moved this week.GET /situations/{id}(get_situation_timeline): the history of the two or three that matter.GET /clusters/{id}(get_cluster): the event you will brief on, with its sources.
The dashboard poll in Developer recipes runs the same shape on a schedule.
How events are formed
- Structured for ranking. Every event carries an outlet count and a significance score from 1 to 10, a model's reading of the coverage, so an analyst or an agent can sort what moved.
- Multi-outlet by construction. An event surfaces once more than one outlet is covering it, so a desk sees stories the press is reporting, not single-source noise, and the outlet count shows how broadly.
- It shows what the press reports. Where outlets give different accounts, as in the Hormuz entry above, a summary can carry both, with the sources linked.
- History windows. Listing and search reach back 7 days on Free (100 requests and 10 searches a day), 30 days on Builder (5,000 and 250). A situation's timeline goes back to its start on every tier.
- English output from sources in many languages; see Multilingual news API.
How it compares
Categories, not named products; individual products vary.
| CLSTR | Event-coded datasets | Raw article APIs | |
|---|---|---|---|
| Unit | One event, linked into situations | One coded record per event | One row per article |
| How widely reported | Outlet count per event | Varies | You count it |
| Story context | Situation timeline back to its start | Varies | You build it |
Start
- Connect an assistant or framework: MCP server for news.
- Choosing a source for an agent: News API for AI agents.
- See how events form: News clustering API.
- What the pipeline reads: the observatory.
- Compare tiers: pricing.
- Endpoints, fields and caps: API and MCP reference.