Skip to main content

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.

​
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 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.
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. 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 confidence_profile=precise, which requires analyst-ready confidence and linked primary/strong Story evidence. Add confidence_profile=loose only when you need exhaustive/raw retrieval, or min_confidence=0.9 for a custom Event confidence floor. 
curl "https://gdeltcloud.com/api/v2/events?event_family=conflict&country=Ukraine&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -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, and date windows.
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 (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={"event_family": "conflict", "country": "Sudan", "category": "Battles", "days": 7}
)
See the GDELT Cloud v2 MCP tools for full parameter documentation.

​
Related Resources

API v2

Clean Events, Stories, summaries, Entities, and geo discovery

GDELT v2 MCP Tools

Progressive Discovery tool reference for AI agent access

ACLED Data Project

Learn about the ACLED methodology and original dataset