> ## 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.
# Atlas GPR
> A Geopolitical Risk index in the tradition of Caldara & Iacoviello, computed from GDELT Cloud's own multilingual narratives and coded events, and normalized so that 100 is each place's own norm.
**Live in preview.** The `/atlas` page is open to signed-in users; the `/api/v2/intelligence/gpr` endpoint and MCP tools are **Admin plan** only. Readings are labeled `provisional` while the baseline matures.
## What it is
**Atlas GPR** answers one question: *how geopolitically tense is this place right now, compared with its own normal?*
It is a deviation index. A reading of `100` means a place is running at its own typical level of geopolitical tension. `180` means 1.8× that level. Crucially, each place is measured **against itself** — never against a global average and never against a leaderboard — so the index is not dominated by the countries that simply generate the most news.
## Why you should care
Raw counts are a trap. The United States and India produce enormous volumes of coded events every day because they are large, media-dense, and heavily covered; Chad does not. Rank countries by event volume and you rebuild a map of media attention, not of risk.
Normalizing against a place's own baseline removes that. A GPR spike in a quiet country is visible precisely because it is unusual *there* — which is the signal a monitoring desk actually wants, and the one raw volume buries.
## What it is useful for
* **Monitoring and tripwires.** "Tell me when this place moves materially above its own norm" is a well-posed query against a deviation index, and a meaningless one against raw counts.
* **A macro risk-premium input.** Geopolitical risk indices are established inputs to oil, defense, and risk-premium models. Atlas GPR provides a multilingual, per-country, drill-through version.
* **Narrative triage.** The Attention lens tells you what the world is preoccupied with; the Events lens tells you what actually happened. The gap between them is itself informative.
* **Evidence gathering.** Every reading drills to the underlying narratives and coded events, so an index move becomes a reading list rather than an alert you have to go re-research.
## Two lenses on the same question
Atlas GPR is served through **two independent lenses**, switchable on the page and via the `variant` parameter.
| | **Attention** lens | **Events** lens |
| ---------------------------- | -------------------------------------------------------- | --------------------------------------------------- |
| Measures | What share of the **news** is about geopolitical tension | What share of **coded events** is tension-bearing |
| Faithful to | The Fed's GPR (an attention measure) | Our own event record (a conflict-intensity measure) |
| Built from | Stories (`GET /api/v2/stories`) | Coded events (`GET /api/v2/events`) |
| Independent of event coding? | **Yes** | No |
| `variant` | `attention` | `fullspectrum` |
Both lenses produce a `tension_share` in `[0,1]`, normalized identically:
```
Atlas GPR = 100 × tension_share ÷ baseline_mean
```
where `baseline_mean` is that place's own average `tension_share` over the trailing \~90-day baseline window.
### The Attention lens
Plain language: *of all the news attention on this place, how much is about war, threats, and conflict?* This is the lens most faithful to the original GPR.
**Numerator** = the total **article count** of the **narratives whose headline is tension-bearing** (matched against a war/threat keyword dictionary).
**Denominator** = the total **article count** of **all narratives** for the place.
* **Inputs:** the **Stories** primitive — `GET /api/v2/stories`. Each Story is a cluster of articles about one narrative and carries an `article_count` (its media footprint). A 300-article narrative counts 300× a single wire brief.
* **What counts as tension:** a GPR-style keyword dictionary (war, strike, missile, sanction, blockade, incursion, …) applied to each narrative's headline — the same *idea* as the Fed's GPR, run over our **multilingual** stream.
* **Geography:** country readings use narratives that **name that country**, exactly how the Fed builds GPRC. The **world** reading uses every narrative, so it is the most robust reading Atlas produces.
### The Events lens
Plain language: *of all the events we coded for this place, how much of the coded activity is conflict?* Grounded in structured events, so you can drill from the index straight to incidents.
**Numerator** = the sum of **event significance** over **tension-bearing coded events**.
**Denominator** = the sum of **event significance** over **all coded events** for the place.
The four components of the decomposition:
| Component | What it captures | Rooted in |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| **Threats** (GPRT) | Coercive intent before violence — demands, threats, force posture, sanctions, broken ties | CAMEO+ POLITICAL coercion categories |
| **Acts** (GPRA) | Violence carried out — battles, explosions / remote violence, violence against civilians (peaceful protests excluded) | Conflict event types |
| **Material** | The high-severity end — Acts plus strongly-negative events | A severity lens (Goldstein) across Threats + Acts |
| **Verbal** | Mild rhetorical friction that is not a coercive threat — criticism, condemnation, accusations | CAMEO+ "disapprove" |
**Do not correlate components against each other using `tension_share`.** Threats, Acts, Material, and Verbal are shares of a common denominator, so they are compositional and will anti-correlate for purely mechanical reasons. In our own testing, a threats-versus-acts correlation on shares produced a spurious −0.17 that vanished to +0.03 when recomputed on event counts. Use the raw counts for any cross-component analysis.
## How to read a reading
* **×norm.** `100` = normal for that place; `150` = 1.5× its usual; `<100` = quieter than usual.
* **Bands.** Subdued · Normal · Elevated · Surging · Extreme — anchored so the global top-decile of material conflict can never band as merely "Normal."
* **NULL, not `0`.** Below the coverage floor (world 0 · continent 80 · region 40 · country 20), the reading is `insufficient_data`.
* **Provisional.** The baseline is a labeled \~90-day provisional window. Series are comparable only within a fixed methodology + coder version.
## Status and honest limits
**Country coverage is the binding constraint today.** Measured over the 107 days from 2026-04-05 to 2026-07-20 across 206 countries:
* Only **2 countries** (United States, India) clear the per-country coverage floor on 90 or more days
* Only **12** clear it on a majority of days; **162 never clear it once**
* The median country has **22 active days and about 25 events** across the entire period
* The top 10 countries account for **58.6%** of all qualifying events
Every country below the floor is returned as `insufficient_data`, not as a number. **Treat world and continent readings as usable and country readings as preview.**
Two further limits worth stating plainly:
* **History is short.** Consistently coded events begin in **March 2026**, and the index itself starts 2026-04-05. Any time-series study of Atlas GPR is capped at a few months, which is not enough to establish predictive power. We are accruing history rather than claiming it.
* **Validation is concurrent, not predictive.** Against the published GPR daily series, our Attention lens tracks moderately (roughly 0.5 on weekly movements) and the Events lens intentionally measures a different quantity — conflict intensity rather than media attention. We have **not** demonstrated that Atlas GPR forecasts market or macro outcomes, and we do not claim it.
## What we are trying to do
The goal is a geopolitical risk index that is multilingual, per-country, drillable to evidence, and composable with asset and entity data — the things the classic GPR, by design, is not.
The near-term roadmap is coverage and history, in that order: deepen per-country coverage until the floor stops suppressing most of the map, and accrue enough consistent history to replace the provisional baseline with a real one and publish splice factors.
## How Atlas differs from the classic GPR
| | Classic GPR | Atlas GPR |
| ------------- | ---------------------------------- | ------------------------------------------------------------- |
| Language | English-language newspapers | **Multilingual** global stream |
| Signal | Newspaper text frequency | **Attention** *and* an event-grounded **Events** lens |
| Geography | Global + country co-mention (GPRC) | World → continent → region → **country**, drill-through |
| Attribution | Not per-incident | Events lens drills to the **underlying coded events** |
| Normalization | Fixed base period = 100 | Each place's **own** \~90-day norm = 100 |
| History | Back to 1900 | **From March 2026** — our clear disadvantage |
| Transparency | Published methodology | **Glass-box** — every number reproducible from the public API |
## Frequently asked questions
No. Atlas GPR is **inspired by** the Caldara–Iacoviello GPR and built in the same spirit, but it is an **independent** index computed from GDELT Cloud's own multilingual Stories and Events. We do not use or redistribute the Fed's series.
Use **Attention** for the GPR-style "how preoccupied is the world" barometer, comparable to the classic index. Use **Events** for a grounded, drill-to-incident measure of coded conflict, or when you need to pivot from the index into the specific events driving it.
Below the coverage floor, Atlas **withholds** the reading rather than emit a misleading `0`. Given the coverage reality above, this is the expected outcome for most countries today. Broaden to region or continent for a reliable reading.
Not on our evidence. We have shown concurrent tracking against the published GPR, not predictive power, and our history is too short to establish it. Treat Atlas GPR as a monitoring and evidence-gathering tool until a real backtest exists.
## API
Parameters include `level`, `geo`, `variant` (`attention` | `fullspectrum`), `component`, `window`, and `date_*`. Returns the reading, band, `tension_share`, coverage, and the baseline used — or `insufficient_data`. Try it in the API Arena.