> ## 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.
# Magnitude
> What `magnitude` measures, what you can do with it, how it is computed, and what it does not claim.
Intensity WITHIN this event's own domain (0-10). The coder picks the path whose native unit the event actually has and reports ONE observable; a fixed published formula turns it into the score.
## What it is for
* Ranking incidents WITHIN one domain — the ten most intense strikes this week, the worst outages this month.
* Setting a floor on a monitoring feed so a trickle of minor incidents does not bury a severe one (`magnitude_min`).
* Separating a fatal clash from a non-lethal one without parsing casualty prose yourself.
* Reading severity where no one died — a grid collapse or a mass displacement scores on its own domain scale rather than at zero.
## Filter on it
`magnitude_min` and `magnitude_max` on `GET /api/v2/events`, range `0`–`10`. Published only for the **cameoplus** family — filtering on it excludes every event outside that family.
## Formula
$$
\text{magnitude} =
\begin{cases}
0 & \text{conflict},\; d = 0 \\[4pt]
\min\!\bigl(10,\; 2 + 2\log_{10} d\bigr) & \text{conflict},\; d > 0 \\[4pt]
\operatorname{clamp}(t,\, 0,\, 10) & \text{hazard, verbal, economic}
\end{cases}
$$
| Symbol | What it is |
| ------ | ------------------------------------------------------------------------------------------------------------------------ |
| $d$ | the fatality COUNT on the conflict path — a real count, not a tier. `-1` when the text states none, which yields `null`. |
| $t$ | the 0–10 severity TIER on the other three paths — hazard impact, CAMEO coercion, or economic impact. |
Every sub-factor is clamped to its stated range before it enters the equation, and the result is rounded to **2 decimal places**. Reproducing a served value needs both.
## What the coder scores
The coder reads these off the article and records a reason for each. The scaler above turns them into the value — nothing else feeds it.
### `path`
conflict = violence with a death toll · hazard = natural/technological disaster · verbal = diplomatic/political speech act · economic = economic/corporate/tech
| Anchor | Meaning |
| ---------- | ---------------------------------------------------------------------------------------- |
| `conflict` | violence with a death toll — the only path that carries a real count rather than a tier. |
| `hazard` | natural or technological disaster. |
| `verbal` | diplomatic or political speech act. |
| `economic` | economic, corporate or technology event. |
### `value`
| Anchor | Meaning |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conflict` | The FATALITY COUNT, not a tier. -1 when no count is stated and none is inferable; never 0, which asserts nobody died. Scored: 1 death → 2.0 · 10 → 4.0 · 100 → 6.0 · 1,000 → 8.0 · 10,000+ → 10 (capped). 0 deaths is a REAL observation (a non-lethal clash) and stays at 0. |
| `hazard` | A 0-10 realized-impact severity tier: 1 minor local · 3 significant local · 5 severe regional · 7 major/national · 9-10 catastrophic. A severity TIER, not a moment magnitude. |
| `verbal` | The CAMEO coercion tier 0-10: peace/truce 1 · appeal/intent 2 · neutral/symbolic 3 · accuse 4 · demand/protest 5 · threaten-nonforce 6 · sanction/threaten-force 7-8 · use-force/invade/mass-violence 9-10. |
| `economic` | An impact tier 0-10: routine 1-3 · significant 4-6 · major/systemic 7-8 · paradigm/collapse 9-10. |
conflict → the FATALITY COUNT (use -1 if no count is stated and none is inferable; do NOT use 0, which asserts nobody died). hazard → a 0-10 realized-impact severity tier (1 minor local · 3 significant local · 5 severe regional · 7 major/national · 9-10 catastrophic; this is a severity TIER, not a moment magnitude — use an Mw reading only when the event IS an earthquake and the text states one). verbal → the CAMEO coercion tier 0-10 (peace/truce 1 · appeal/intent 2 · neutral/symbolic 3 · accuse 4 · demand/protest 5 · threaten-nonforce 6 · sanction/threaten-force 7-8 · use-force/invade/mass-violence 9-10). economic → an impact tier 0-10 (routine 1-3 · significant 4-6 · major/systemic 7-8 · paradigm/collapse 9-10).
## The frameworks it adapts
### [MEPV — Major Episodes of Political Violence](https://www.systemicpeace.org/inscrdata.html)
**What we take from it.** The anchored 1-10 magnitude scale, and Richardson's log-of-deaths slope laid onto it, so a fatality count becomes a tier that is comparable across kinds of violence rather than a raw body count.
*We publish no current third-party application for this one — we adapt the scale, not a live programme.*
### [EM-DAT — the international disaster database](https://www.emdat.be/)
**What we take from it.** The realized-impact severity tier for the hazard path — scoring what a disaster actually did to people and systems, rather than a physical intensity reading.
**In current use by** [UNDRR, which uses EM-DAT as an indicator source for Sendai Framework global-target monitoring](https://www.emdat.be/).
### The full citation trail
Domain severity scales — Richardson Magnitude / MEPV for violence, an EM-DAT-style realized-impact severity tier for hazards, the CAMEO coercion ladder for diplomacy and politics, an anchored impact tier for economic, corporate and technology events. Magnitude compares WITHIN a domain; `significance` is how you sort events against each other.
We ADAPT the structure and vocabulary of these frameworks. **None of the bodies named endorses, reviews, or is connected to this metric**, and their use does not make our values empirical measurements.
## Worked examples
Real events from the corpus, scored by the coder and frozen here on **2026-08-19** — check the arithmetic against the formula above. They are snapshots, not live lookups: an event can be re-coded, and an example that changed underneath its own arithmetic would be worse than none.
### Syrian security forces detain seven after Latakia custody death
*Syria · 2026-08-13*
The conflict path with a real fatality count. One death is the first anchor: 2 + 2·log10(1) = 2.0. A count, not a tier.
| Sub-factor | Value | The coder's reason |
| ---------- | ---------- | --------------------------------------------------------------------------------------------------- |
| `path` | `conflict` | conflict — the article reports a death, so the fatality ladder applies rather than a severity tier. |
| `value` | 1 | One man reportedly died after being beaten in police custody. |
$$
\min\!\bigl(10,\; 2 + 2\log_{10} 1\bigr) = 2 + 0 = \mathbf{2.0}
$$
`magnitude` **= 2** — what `GET /api/v2/events` returns for this event.
### Britain seizes Russian tanker Smyrtos in English Channel
*United Kingdom · 2026-08-13*
The verbal path — the CAMEO coercion ladder. Nobody died, and the event is still a 9, because seizing property by force sits near the top of that ladder.
| Sub-factor | Value | The coder's reason |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `path` | `verbal` | verbal — a coercive state act, scored on the coercion ladder rather than by casualties. |
| `value` | 9 | The United Kingdom reportedly seized a tanker and boarded it using Royal Marines, an imposed coercive action against property. |
$$
\operatorname{clamp}(t,\,0,\,10) = \operatorname{clamp}(9,\,0,\,10) = \mathbf{9.0}
$$
`magnitude` **= 9** — what `GET /api/v2/events` returns for this event.
### Vessel owners reduce Strait of Hormuz traffic amid standoff
*Iran · 2026-08-11*
The economic path. A shipping chokepoint thinning out is a 7 on the impact tier with no casualties and no coercive act at all.
| Sub-factor | Value | The coder's reason |
| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `path` | `economic` | economic — the observable is a change in commercial throughput. |
| `value` | 7 | Traffic fell to eight vessels, below a 10-day average of 12, at a chokepoint previously carrying about 20 million barrels of oil per day. |
$$
\operatorname{clamp}(t,\,0,\,10) = \operatorname{clamp}(7,\,0,\,10) = \mathbf{7.0}
$$
`magnitude` **= 7** — what `GET /api/v2/events` returns for this event.
## When it is `NULL`
`null` when the coder found no usable severity observable — on the conflict path, when the text states no fatality count and none is inferable. `null` means UNKNOWN, and it is never coerced to 0: a 0 on the conflict path is a REAL observation (a non-lethal clash), so the two must not be read the same way. Magnitude is the only one of the four metrics that is served as an explicit `null`; the other three are absent from the response instead.
These are the readings the definition does not support — building on one of them is building on a promise nobody made.
* NOT importance, and NOT comparable across domains. A conflict-9 and a technology-9 are not the same "size". October 7 scores 8.2 on \~1,200 deaths while the Trump-rally shooting scores 2.6 on 2 deaths — physical intensity, not importance. Use `significance`, the only cross-domain ranking number.
* A conflict-path 0 is NOT a missing value — it is a real observation (a non-lethal clash). Unknown is NULL; see `nullWhen`.
* The hazard path is NOT Moment Magnitude (Mw). It is a realized-impact severity tier; Mw is used only when the event IS an earthquake and the text states a reading.
* An unmeasured magnitude is NOT neutral downstream. `significance` drops the magnitude term AND its 0.20 weight when `magnitude_measured = 0`, which is arithmetically identical to mean-imputing the other three metrics into the magnitude slot — a measured swing of up to ±0.22, roughly 4× the noise floor. An event whose magnitude would have been low relative to its other metrics is systematically promoted by being unmeasured, and a high-magnitude one demoted.
What applies to all four metrics — the frameworks we adapt, how thin the registry coverage is, and the smallest single-event difference worth reading — is on [Limits and error bars](/metrics/limits).