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. Public v2 domains:

​
CAMEO+ metrics

Four metrics are scored on CAMEO+ Events (plus goldstein_scale for POLITICAL Events where meaningful). Each is produced by a two-stage split: the coder reads a small set of concrete sub-factors off the source text and states a reason for each, then a fixed published formula — not the model — turns those sub-factors into the served value.

​
magnitude (0–10) — how intense was the event, for its own type?

  • Framework: domain severity scales — Richardson log-deaths (anchored MEPV-style on 0–10) for violence, an EM-DAT-style realized-impact tier for hazards, the CAMEO coercion ladder for speech acts, an anchored impact tier for economic/corporate/technology events.
  • Formula: routes by domain. Conflict → min(10, 2 + 2·log₁₀(deaths)), so 1 death anchors at 2, 10 at 4, 100 at 6, 1,000 at 8 and 10,000+ at 10. Hazard → a 0–10 realized-impact tier. Verbal/diplomatic → the CAMEO coercion tier. Economic → an anchored impact tier. Note that 0 deaths is a real observation (a non-lethal clash), distinct from no count being found.
  • Gate: null when no severity observable was found. null means unknown, not zero — never coerce it to 0. When magnitude is unmeasured, significance drops both the magnitude term and its 0.20 weight.
  • What it is NOT: not comparable across domains, and not a measure of importance. A conflict 8 and an economic 8 are not the same “size,” and a low-fatality attack on a prominent political figure scores low on magnitude however important it is — physical intensity, not consequence. Importance shows up in the other three metrics and in significance, which is what you use to rank across domains.

​
systemic_importance (0–1) — how much does the wider system depend on the node?

  • Framework: the BCBS G-SIB / SIFI assessment methodology, extended with CISA critical-infrastructure sectors and network centrality.
  • Formula: (size + interconnectedness + irreplaceability) / 3 — equal weights, matching BCBS G-SIB (five categories at 20% each) and ECB/EBA O-SII (four at 25%).
  • Gate: none, but the base rate is low — most events touch no systemic node, and the coder must name the node before rating it.
  • What it is NOT: not a count of how many states, populations or sectors are involved. It is a property of the node the event touched. A large firm is not automatically systemic; an unsubstitutable supplier is.

​
propagation_potential (0–1) — are the conditions present for a shock to travel?

  • Framework: transmission-condition assessment — a channel gate, an amplifier core, and a subtractive damper. Adapted from the ERCS barrier model (Commission Delegated Reg. (EU) 2020/2034), the ESRB systemic-risk model, RAND’s escalation-risk framework, and Rinaldi–Peerenboom–Kelly dependency coupling as operationalised for DHS/CISA.
  • Formula: (channel + coupling + breach + primed + (1 − containment)) / 5.
  • Gate: channel ≤ 0.05 → 0. With no live transmission channel the score is 0 regardless of how dramatic the event is.
  • What it is NOT: not a probability and not a forecast of follow-on events. Every sub-factor is a claim about the present, readable from the event text. It carries no per-domain prior — there is no “cyber and supply chain always score higher” base rate in the formula.

​
market_sensitivity (0–1) — how much market-relevant information does it carry?

  • Framework: the reasonable-investor materiality test — the question a disclosure lawyer answers while reading a document, before any price move exists to measure. Adapted from TSC Industries v. Northway (1976) and Basic v. Levinson (1988), and from EU/UK MAR Art. 7(4)‘s ex ante standard.
  • Formula: (claim_exposure + economic_bite) / 2 — equal weights. claim_exposure is how directly the event attaches to a claim that actually exists; economic_bite is whether something occurred that acts on that claim’s economics, or whether this was speech.
  • Gate: claim_exposure ≤ 0.05 → 0. No traded claim exposed, no score. A traded claim is broader than a listed share — credit, contractual and insurance claims count.
  • What it is NOT: not a predicted price move, not a probability, and not an expected return. It is unsigned and indicates no direction — a windfall and a disaster can score identically.
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. Event, Story, and Entity list endpoints default to the exact past 24 hours. Narrow with developer-facing filters such as category, subcategory, country, region, continent, date windows up to 30 days, sort, and pagination.

​
Access

Use API v2 for new integrations:
For MCP agents, use Progressive Discovery:
v1 REST endpoints remain supported for existing direct API users, but v2 is the recommended public interface.