GDELT Cloud Docs — Global Event Data API & MCP

Core articles are the articles that report the story’s own incident. A story’s anchor is its rank-1 article: highest article_weight, ties broken by lowest source_url, over the story’s whole membership.

role	rule
`core`	It is the anchor, or it is same-incident compatible with the anchor — and it is not background framing.
`background_only`	It is background framing: a backdrop article, or a timeline/roundup, analysis, or economic-fallout frame.
`related`	It is not same-incident compatible with the anchor, but it is in the same theater.
`uncertain`	None of the above.

Ranking. Articles are ranked by article_weight descending, ties broken by source_url ascending. Rank 1 is the anchor. Scope. Every rank and every count is defined over the story’s whole membership, never over one ingest batch.

derived field	formula
`core_article_count`	count of distinct articles whose role is core
`background_article_count`	count of distinct articles whose role is background_only
`cluster_certainty`	core_article_count / article_count
`event_readiness`	clamp01(cluster_certainty + (article_count >= 2 ? 0.2 : 0) - (background_article_count > 0 ? 0.15 : 0))
`singleton_score`	0 for any story with 2 or more articles

Invariants.

core_article_count + background_article_count <= article_count
a story with 2 or more articles has singleton_score = 0
representative_article_uid, _source_url, _title and _domain describe one and the same article

Known limitation. A story’s anchor changes only when a strictly higher-ranked article joins it. Roles already stamped are not re-derived when that happens, because the gate features they were derived from are not retained.

How to read this

The surface

Vocabulary

Metrics

Stories

Event codes

CAMEO Political codes

CAMEO+ domain codes

Core articles