Skip to main content

​
Overview

GDELT Cloud generates structured Event records from clustered Stories. Public API v2 exposes two Event families: Every public Event links back to Story evidence where available and is shaped for analyst workflows: normalized geography, actors, categories, metrics, linked Stories, linked Entities, and top articles.
GDELT Cloud independently generates its Conflict Event records from GDELT Cloud Story clusters. We follow ACLED-style methodology where useful, but do not use, license, or redistribute ACLED’s proprietary dataset.

​
Conflict Events

Conflict Events cover:
  • battles
  • explosions and remote violence
  • violence against civilians
  • protests
  • riots
  • strategic developments
Typical fields include:
  • category and subcategory
  • actors
  • geo.country, geo.region, geo.continent, geo.admin1, geo.location, geo.latitude, geo.longitude
  • metrics.significance
  • metrics.goldstein_scale
  • has_fatalities and fatalities
  • civilian_targeting and civilian_targeting_label for Conflict Events
  • story_refs, entity_refs, and top_articles
Use has_fatalities=true for fatality monitoring. v2 intentionally does not expose fatality min/max filters. Use civilian_targeting=true for Conflict Events where civilians were coded as the primary target.

​
CAMEO+ Events

CAMEO+ is the GDELT Cloud generated event layer for political and structural developments outside the Conflict family. CAMEO+ covers ten domains outside the Conflict family — political, economic, corporate, technology, infrastructure and five more. Rather than repeat the list here, the domain code reference publishes every one with the definition the coder actually receives, plus what each domain explicitly includes and excludes.

​
How the metrics are produced

Four metrics are scored on CAMEO+ events, and each is produced by a two-stage split that is the whole reason the numbers are auditable:
  1. The coder reads a small set of concrete sub-factors off the source text and states a reason for each — “the node is unsubstitutable because…”, not “this is a 0.7.”
  2. A fixed, published formula — not the model — turns those sub-factors into the served value.
The model never chooses the final number. That is what makes a score checkable: you can read the sub-factors, apply the formula yourself, and get the same answer. Two conventions matter more than the individual definitions:
  • null means unknown, never zero. When an observable was not found, the metric is null and the term drops out of the blend along with its weight — so an event is never penalised for something we failed to observe. Coercing null to 0 invents a reading.
  • Some metrics are gated. Below a threshold on one sub-factor the whole metric is 0 regardless of the others. That is the metric working: an event with no live transmission channel does not propagate, however dramatic it is.
Every formula, sub-factor, anchor, gate and NULL rule is in the event metric reference — generated from the same objects the coder receives, so it cannot drift from what ran. Two real events scored by hand are in worked examples.
Each metric also publishes what it does not claim. The most common misreading is treating market sensitivity as a severity score — a national blackout scores low on it and high on everything else, because it measures attachment to a traded claim rather than how bad an event is.
How to read magnitude, systemic_importance, propagation_potential and market_sensitivity. These four are rubric scores, not measurements. Read this before using any of them in a threshold, a model feature, or a customer-facing claim.
Rubric scores, not measurements. For each metric, a model reads a handful of concrete sub-factors off the source text — a fatality count, how substitutable a supplier is, whether a barrier that was holding got breached, whether a traded claim is exposed — and states a reason for each one. Fixed, published formulas then turn those sub-factors into the score. Nothing is fitted, estimated from price history, or forecast, and nothing is a black box: any value is reconstructable by a third party from the sub-factors and the published formula. The frameworks give the rubric its structure — they do not make the values empirical. magnitude follows domain severity scales (Richardson log-deaths, anchored MEPV-style on 0–10; an EM-DAT-style realized-impact tier for hazards; the CAMEO coercion ladder for speech acts). systemic_importance follows the BCBS G-SIB / ECB O-SII equal-weight indicator practice. propagation_potential follows the ERCS barrier model and the ESRB systemic-risk shape. market_sensitivity follows the reasonable-investor materiality test. We adapt these frameworks for their vocabulary and structure. None of these institutions endorses, reviews, or is connected to this work, and their use does not make our values measured. Coverage — why “measured” is the wrong word. Over 42,099 events in a 45-day window: a hard registry attribute — the observable that would make systemic_importance measured rather than judged — resolves for about 2.2% of events, and a traded instrument, behind market_sensitivity’s exposure gate, resolves for about 1.5%. For everything else the score is a judged rubric reading. Treat all four as ordinal ranking signals: use them to sort, filter and triage, not to assert a quantity about a single event. Reliability — the smallest difference worth reading. The same 59 events, coded three times with identical prompts and formulas, so everything that moved is noise: Never read a single-event difference smaller than the last column. Distribution-level comparisons are far steadier than individual events, so aggregate claims hold well below these thresholds — but a claim that one event moved does not. magnitude is within-domain only. Each domain has its own anchored ladder, so a conflict magnitude of 8 and an economic magnitude of 8 are not the same “size.” Use significance — the family-scoped composite — whenever you rank events across domains. And magnitude is null when no severity observable was found: null means unknown, never zero. The four are not fully independent axes. Under the ESRB framing, market_sensitivity is a propagation channel — common exposure and confidence effects expressed in prices — so it is closer to a special case of propagation_potential than an orthogonal dimension. Both are served because market_sensitivity carries substantial independent variance and fires domain-appropriately, but do not treat the set as four independent dimensions in a model or a weighted score.

​
Goldstein Scale

metrics.goldstein_scale is public and important:
  • present for all Conflict Events
  • present for CAMEO+ POLITICAL Events where meaningful
  • null for non-political CAMEO+ domains
It ranges from cooperative to conflictual:

​
Ranking

v2 uses one canonical significance score for Events and Stories. Event significance combines factors such as Goldstein severity where meaningful, CAMEO+ metrics, fatalities for Conflict Events, article evidence volume, and confidence. It is family-scoped: each event’s raw total is divided by the maximum its own family can reach, so Conflict and CAMEO+ events both span a true 0–1 and stay comparable — see Ranking for the exact weights. Story significance combines linked Event significance, article count with caps to prevent noisy volume dominance, and recency. Default sort is sort=significance; use sort=recent when freshness matters most. Without explicit dates, Event and Story lists use the last 24 hours, or 30 days when filtering by entity. Read meta.query_window for the effective bounds. Other families differ; see their API reference. Narrow with a date window and any of the filters in the parameter reference, whose legal values are in the value reference.

​
Access

Use API v2 for new integrations:
For MCP agents, use Progressive Discovery:
v1 is retired: every /api/v1/* path returns 410 Gone naming its v2 replacement. See API keys for the mapping.