> ## 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.
# Conflict Data
> AI-coded political violence and protest events using the ACLED methodology
## What is Conflict Data?
GDELT Cloud's **Conflict Data** feature provides generated structured records of political violence, armed conflict, protests, riots, and strategic developments derived from GDELT Cloud Story clusters. Events follow ACLED-style methodology and taxonomy, but are independently generated by GDELT Cloud.
Events are generated automatically from the same Story clusters that power the GDELT Cloud Stories surface, giving you a structured, queryable conflict layer linked back to article evidence.
GDELT Cloud conflict data is modeled after the [ACLED codebook](https://acleddata.com/resources/general-guides/) and follows ACLED's classification hierarchy, actor typing, and geographic coding conventions. **GDELT Cloud independently generates its own conflict event records from GDELT Cloud Story clusters built from the upstream GDELT Project article stream — we do not use, license, or re-distribute ACLED's proprietary dataset.** The ACLED badge indicates we follow ACLED methodology and taxonomy, not that we source from ACLED.
Learn more about the ACLED project at [acleddata.com](https://acleddata.com).
**Beta:** GDELT Cloud conflict event coding is in beta. Classification accuracy, coverage, and field definitions will improve over time.
## Event Structure
Each conflict event follows the 3-level ACLED classification hierarchy:
```
disorder_type (top level)
└── event_type (mid level)
└── sub_event_type (most specific)
```
### Disorder Types
| Disorder Type | Covers |
| -------------------------- | ------------------------------------------------------------ |
| **Political violence** | Armed conflict, attacks, explosions, targeted violence |
| **Demonstrations** | Protests, riots, mob violence |
| **Strategic developments** | Agreements, arrests, territorial changes, base establishment |
### Event Types & Sub-types
Armed combat between organized groups.
* **Armed clash** — mutual exchange of fire; neither side clearly won/lost territory
* **Government regains territory** — state forces retake area from non-state actors (confirmed control change)
* **Non-state actor overtakes territory** — armed group captures territory (confirmed control change)
Attacks using weapons that allow distance between attacker and target.
* **Air/drone strike** — aerial bombardment by aircraft or drone
* **Shelling/artillery/missile attack** — indirect fire (artillery, rockets, mortars, missiles)
* **Remote explosive/landmine/IED** — planted device detonates; attacker not present
* **Suicide bomb** — attacker intends to die in the blast
* **Grenade** — grenade thrown or launched
* **Chemical weapon** — chemical agents used
Deliberate violence by armed actors targeting unarmed non-combatants.
* **Attack** — lethal violence or targeted assassination
* **Abduction/forced disappearance** — non-lethal taking or detention
* **Sexual violence** — sexual violence by armed actors against civilians
Organized demonstrations.
* **Peaceful protest** — no violence by protesters or security forces
* **Protest with intervention** — security forces use non-lethal crowd control
* **Excessive force against protesters** — security forces use lethal force
Collective violence, often spontaneous.
* **Violent demonstration** — protesters initiate violence (arson, projectiles, property destruction)
* **Mob violence** — spontaneous communal clashes between civilian groups
Concrete actions that change the conflict landscape.
* **Agreement** — signed ceasefire, peace deal, or diplomatic accord
* **Arrests** — named political or military figure arrested
* **Headquarters or base established** — military base formally established or force deployed
* **Looting/property destruction** — confirmed looting event
* **Non-violent transfer of territory** — formal handover without combat
* **Change to group/activity** — confirmed change in armed group structure/activity
* **Disrupted weapons use** — weapons cache confirmed seized or interdicted
* **Other**
## Actor Coding
Each event records up to two actors using the ACLED actor typing system:
| Code | Actor Type | Description |
| ---- | ------------------------- | -------------------------------------------------------------------------------- |
| 1 | **State forces** | Government military, police, intelligence services, state-commanded paramilitary |
| 2 | **Rebel groups** | Non-state armed groups seeking to overthrow the national government |
| 3 | **Political militias** | Armed groups with political objectives short of overthrowing the state |
| 4 | **Identity militias** | Communal groups organized around ethnic, religious, or clan identity |
| 5 | **Rioters** | Individuals engaged in unorganized collective violence |
| 6 | **Protesters** | Individuals or crowds engaged in organized demonstrations |
| 7 | **Civilians** | Unarmed non-combatants (always actor2 in violence against civilians) |
| 8 | **External/Other forces** | Foreign military, international coalitions, UN peacekeepers |
The `interaction` field encodes the actor pair as a normalized label: `'State forces–Rebel groups'`, `'State forces–Civilians'`, `'Protesters only'`, etc.
## Geographic Coding
Each event is located at up to 4 levels of precision:
* **country** — full English country name (e.g. `Ukraine`, `Gaza Strip`)
* **admin1** — state or province (e.g. `Donetsk Oblast`, `Khartoum`)
* **admin2 / admin3** — district and sub-district (when available)
* **location** — named place (city, town, military base)
* **latitude / longitude** — decimal coordinates (when available)
`geo_precision` indicates confidence: `1` = exact location known, `2` = general area, `3` = region/province only.
## Data Quality
| Field | Notes |
| ----------------------- | ------------------------------------------------------------------------------------------------------------- |
| **fatalities** | Best-supported most likely figure from the sources (not automatically the lowest). Disputes noted in `notes`. |
| **civilian\_targeting** | Only `true` when civilians are the *primary* target, not incidental collateral harm. |
| **confidence** | AI coding confidence 0–1. Lower values indicate ambiguous or indirect sources. |
| **time\_precision** | `1` = exact day known, `2` = within a week, `3` = within a month. |
## Accessing Conflict Data
### Dashboard
Visit **Events** in the sidebar, then select the **Conflict** tab to browse, filter, and map conflict events. Use the filter bar to narrow by country, event type, disorder type, and more. Each event card links to the source news cluster.
Story cards display linked Events when generated Conflict Events exist. Use the v2 Stories and Events APIs to move between narrative evidence and structured event records.
### REST API
Event list and summary calls default to the exact past 24 hours. Narrow with developer-facing filters such as event-type `category` values, sub-event-type `subcategory` values, `civilian_targeting=true`, country/region/continent filters, date windows up to 30 days, `sort`, and pagination. The legacy `event_family=conflict` filter is still accepted for existing clients, but new integrations should use `category=Battles`, `category=Protests`, and the other Conflict event types directly.
```bash List recent events theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=Battles&subcategory=Armed%20clash&country=Ukraine&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
-H "Authorization: Bearer gdelt_sk_..."
```
```bash Filter by type theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=Explosions%2FRemote%20violence&subcategory=Air%2Fdrone%20strike&date_start=2026-04-11&date_end=2026-04-17" \
-H "Authorization: Bearer gdelt_sk_..."
```
```bash Civilian targeting theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=Violence%20against%20civilians&civilian_targeting=true&date_start=2026-04-11&date_end=2026-04-17" \
-H "Authorization: Bearer gdelt_sk_..."
```
```bash Semantic search theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=Explosions%2FRemote%20violence&subcategory=Air%2Fdrone%20strike&search=airstrikes%20civilian%20infrastructure&date_start=2026-04-11&date_end=2026-04-17" \
-H "Authorization: Bearer gdelt_sk_..."
```
```bash Semantic search + filter theme={null}
curl "https://gdeltcloud.com/api/v2/events?category=Battles&subcategory=Armed%20clash&search=rebel%20armed%20clash%20territory&country=Sudan&date_start=2026-03-18&date_end=2026-04-17" \
-H "Authorization: Bearer gdelt_sk_..."
```
### Semantic Search
The v2 `search` parameter accepts natural-language queries and ranks results by semantic similarity when embeddings are available.
Semantic search is composable with structured filters such as `country`, `region`, `continent`, `category`, `subcategory`, `has_fatalities`, `civilian_targeting`, and date windows.
**Example queries that work well:**
| Query | What it finds |
| --------------------------------------------- | ------------------------------------------------ |
| `"airstrikes civilian infrastructure"` | Air/drone strikes on homes, utilities, hospitals |
| `"protest government crackdown"` | Demonstrations with security force intervention |
| `"rebel advance territorial control"` | Non-state actors seizing or holding territory |
| `"military offensive shelling artillery"` | Artillery and missile attacks in active fronts |
| `"ceasefire agreement peace deal"` | Strategic developments / agreements |
| `"kidnapping abduction forced disappearance"` | Violence against civilians — abductions |
**When to use `search` vs structured filters:**
* Use structured filters (`category`, `subcategory`, `country`, `region`, `continent`) when you know the taxonomy value
* Use `search` when describing a situation in plain language, or when the precise sub-type is uncertain
* Combine both: `search=artillery shelling front line&country=Ukraine` narrows geography while ranking semantically
### MCP Tool
For AI agents, use Progressive Discovery and call `search_events`:
```
gdelt_cloud_tool_call(
tool_name="search_events",
tool_arguments={"country": "Sudan", "category": "Battles", "subcategory": "Armed clash", "days": 7}
)
```
See the [GDELT Cloud v2 MCP tools](/mcp/tools/gdelt-cloud) for full parameter documentation.
## Related Resources
Clean Events, Stories, summaries, Entities, and geo discovery
Progressive Discovery tool reference for AI agent access
Learn about the ACLED methodology and original dataset