Skip to main content

​
What is Conflict Data?

GDELT Cloud’s Conflict Data feature provides structured records of political violence, armed conflict, and protest events derived from GDELT news clusters. Each event is coded using the ACLED (Armed Conflict Location & Event Data) methodology — the industry standard for tracking political violence and demonstrations worldwide. Events are generated automatically by AI from the same news clusters that power the Media Events feed, giving you a structured, queryable conflict layer on top of real-time global news.
GDELT Cloud conflict data is modeled after the ACLED codebook and follows ACLED’s classification hierarchy, actor typing, and geographic coding conventions. GDELT Cloud independently generates its own conflict event records from GDELT news clusters — 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.
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 TypeCovers
Political violenceArmed conflict, attacks, explosions, targeted violence
DemonstrationsProtests, riots, mob violence
Strategic developmentsAgreements, 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:
CodeActor TypeDescription
1State forcesGovernment military, police, intelligence services, state-commanded paramilitary
2Rebel groupsNon-state armed groups seeking to overthrow the national government
3Political militiasArmed groups with political objectives short of overthrowing the state
4Identity militiasCommunal groups organized around ethnic, religious, or clan identity
5RiotersIndividuals engaged in unorganized collective violence
6ProtestersIndividuals or crowds engaged in organized demonstrations
7CiviliansUnarmed non-combatants (always actor2 in violence against civilians)
8External/Other forcesForeign 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

FieldNotes
fatalitiesConservative estimate — lowest reported figure. Disputes noted in notes.
civilian_targetingOnly true when civilians are the primary target, not incidental collateral harm.
confidenceAI coding confidence 0–1. Lower values indicate ambiguous or indirect sources.
time_precision1 = 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. Media event story cards on the Media Events page display a ⚔️ Conflict badge when linked conflict events exist. Use the Conflict Events Only toggle in the filter bar to show only stories with associated conflict events.

​
REST API

curl "https://gdeltcloud.com/api/v1/conflict-events?days=7&country=Ukraine" \
  -H "Authorization: Bearer gdelt_sk_..."
The search parameter accepts natural-language queries and ranks results by semantic similarity to the event’s AI-generated notes field using text-embedding-3-small (1536 dimensions).
Semantic search re-ranks results by cosine distance between your query embedding and the pre-computed event note embeddings. Results are sorted most-similar first instead of the default reverse-chronological order. All other filters (country, event_type, disorder_type, days, etc.) still apply — semantic search and structured filters are fully composable.
Example queries that work well:
QueryWhat 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 (event_type, country, disorder_type) when you know the exact ACLED 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 the get_conflict_events MCP tool: 
get_conflict_events(days=7, country="Sudan", event_type="Battles")
See the get_conflict_events tool reference for full parameter documentation.

Conflict Events API

Full REST API reference for the conflict events endpoint

get_conflict_events MCP Tool

MCP tool reference for AI agent access

Media Events

Browse the news clusters that underpin conflict events

ACLED Data Project

Learn about the ACLED methodology and original dataset