API
← API and MCP docs

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

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

  1. GET /situations?category=international&country=IR,SA,YE&days=7 (get_top_situations, window: "7d"): what moved this week.
  2. GET /situations/{id} (get_situation_timeline): the history of the two or three that matter.
  3. 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

How it compares

Categories, not named products; individual products vary.

CLSTREvent-coded datasetsRaw article APIs
UnitOne event, linked into situationsOne coded record per eventOne row per article
How widely reportedOutlet count per eventVariesYou count it
Story contextSituation timeline back to its startVariesYou build it

Start