> ## Documentation Index > Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Event Coding: Conflict & CAMEO+ > How GDELT Cloud generates structured Conflict and CAMEO+ Events from Story clusters. ## Overview GDELT Cloud generates structured Event records from clustered Stories. Public API v2 exposes two Event families: | Family | Meaning | | ----------- | -------------------------------------------------------------------------- | | `conflict` | Conflict, political violence, protests, riots, and strategic developments. | | `cameoplus` | Political and structural Events across public CAMEO+ domains. | 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: | Domain | Covers | | ---------------- | ----------------------------------------------------------------------------------------------------------------- | | `POLITICAL` | CAMEO-style diplomatic, cooperative, verbal conflict, and non-violent coercive actions. | | `ECONOMIC` | Macro, monetary, fiscal, trade, market stress, currency, and sovereign debt events. | | `CORPORATE` | M\&A, bankruptcy, production capacity, capital allocation, legal/regulatory, leadership, and supply-chain shocks. | | `TECHNOLOGY` | AI, cyber, strategic technology controls, space, military technology, and critical tech infrastructure. | | `INFRASTRUCTURE` | Energy, transport, supply chain, communications, sabotage, and water infrastructure. | | `HEALTH` | Outbreaks, public health emergencies, vaccines/treatments, policy actions, and health-system stress. | | `INFORMATION` | Disinformation, information control, major leaks, and narrative warfare. | | `ENVIRONMENT` | Geophysical hazards, meteorological hazards, climate events, pollution, and environmental policy. | ## 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: | Metric | Repeat-coding movement (mean within-event SD) | Smallest defensible single-event difference | | ----------------------------- | --------------------------------------------- | ------------------------------------------- | | `magnitude` (0–10) | \~0.36 | **0.72** | | `systemic_importance` (0–1) | \~0.03 | **\~0.07** | | `propagation_potential` (0–1) | \~0.03 | **\~0.07** | | `market_sensitivity` (0–1) | \~0.03 | **\~0.07** | **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: | Range | Meaning | | ------------- | ----------------------------------------------------------- | | `+5` to `+10` | Cooperative, conciliatory, or de-escalatory action. | | `-4` to `+4` | Neutral, mixed, low-intensity, or context-dependent action. | | `-5` to `-10` | Conflictual, coercive, violent, or severe action. | ## 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](/api-reference/concepts#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: ```bash theme={null} GET /api/v2/events GET /api/v2/events/{event_id} GET /api/v2/events/summary GET /api/v2/stories GET /api/v2/stories/{story_id} GET /api/v2/stories/{story_id}/articles ``` For MCP agents, use Progressive Discovery: ```json theme={null} { "tool_name": "search_events", "tool_arguments": { "category": "INFRASTRUCTURE", "country": "United States", "days": 14, "sort": "significance" } } ``` v1 REST endpoints remain supported for existing direct API users, but v2 is the recommended public interface.