Skip to main content

​
Overview

get_conflict_events returns structured conflict event records derived from GDELT news clusters. Each event is coded using the ACLED (Armed Conflict Location & Event Data) methodology — the same framework used by researchers and analysts worldwide to track political violence and protest. Events cover battles, airstrikes, protests, riots, and strategic developments globally, with each record linked back to the source media event cluster via cluster_id.

​
Parameters

ParameterTypeDefaultDescription
daysinteger1Lookback window in days from date. Max 30.
datestringtoday UTCAnchor/end date in YYYY-MM-DD format.
limitinteger20Events to return (max 100).
offsetinteger0Pagination offset.
countrystring—Full English country name (e.g. 'Ukraine', 'Sudan', 'Gaza Strip').
admin1string—State/province name. Use with country (e.g. 'Donetsk Oblast').
disorder_typeenum—'Political violence', 'Demonstrations', 'Strategic developments'
event_typeenum—'Battles', 'Protests', 'Riots', 'Explosions/Remote violence', 'Violence against civilians', 'Strategic developments'
sub_event_typeenum—25 ACLED sub-types (see below).
interactionenum—ACLED actor-pair label. See full enum list below.
civilian_targetingboolean—If true, only events where civilians were the primary target.
fatalitiesboolean—If true, only events with reported fatalities > 0.
searchstring—Natural-language semantic search query. Ranks results by cosine similarity to event notes (text-embedding-3-small, 1536 dims) instead of chronological order. Fully combinable with all other filters. Examples: 'airstrikes civilian infrastructure', 'rebel advance territorial control', 'protest government crackdown'.

​
Sub-event Types

The full ACLED sub-event taxonomy:
CategorySub-event types
BattlesArmed clash, Government regains territory, Non-state actor overtakes territory
ProtestsPeaceful protest, Protest with intervention, Excessive force against protesters
RiotsViolent demonstration, Mob violence
Explosions/Remote violenceAir/drone strike, Shelling/artillery/missile attack, Remote explosive/landmine/IED, Suicide bomb, Grenade, Chemical weapon
Violence against civiliansAttack, Abduction/forced disappearance, Sexual violence
Strategic developmentsAgreement, Arrests, Headquarters or base established, Looting/property destruction, Change to group/activity, Disrupted weapons use, Non-violent transfer of territory, Other

​
Interaction Values

The full ACLED actor-pair label enum (ordering always puts the lower-numbered actor type first):
Actor groupValues
State forcesState forces only, State forces–State forces, State forces–Rebel groups, State forces–Political militias, State forces–Identity militias, State forces–Rioters, State forces–Protesters, State forces–Civilians, State forces–External/Other forces
Rebel groupsRebel groups only, Rebel groups–Rebel groups, Rebel groups–Political militias, Rebel groups–Identity militias, Rebel groups–Rioters, Rebel groups–Protesters, Rebel groups–Civilians, Rebel groups–External/Other forces
Political militiasPolitical militias only, Political militias–Political militias, Political militias–Identity militias, Political militias–Rioters, Political militias–Protesters, Political militias–Civilians, Political militias–External/Other forces
Identity militiasIdentity militias only, Identity militias–Identity militias, Identity militias–Rioters, Identity militias–Protesters, Identity militias–Civilians, Identity militias–External/Other forces
RiotersRioters only, Rioters–Rioters, Rioters–Protesters, Rioters–Civilians, Rioters–External/Other forces
ProtestersProtesters only, Protesters–Protesters, Protesters–Civilians, Protesters–External/Other forces
CiviliansCivilians only, Civilians–Civilians
External/Other forcesExternal/Other forces–Civilians, External/Other forces only, External/Other forces–External/Other forces

​
Data Structure

Each returned event contains: 
{
  "id": "uuid",
  "cluster_id": "...",          // links to media event cluster
  "event_date": "2026-07-01",
  "disorder_type": "Political violence",
  "event_type": "Explosions/Remote violence",
  "sub_event_type": "Air/drone strike",
  "actor1": "Russian Armed Forces",
  "actor2": "Civilians",
  "interaction": "State forces–Civilians",
  "civilian_targeting": true,
  "country": "Ukraine",
  "admin1": "Kharkiv Oblast",
  "location": "Kharkiv",
  "latitude": 49.988,
  "longitude": 36.232,
  "fatalities": 3,
  "notes": "Russian forces conducted an airstrike on residential areas...",
  "tags": ["civilians targeted"],
  "confidence": 0.92,
  "source_urls": ["https://..."]
}

​
Classification Hierarchy

Events follow the 3-level ACLED classification: 
disorder_type
  └── event_type
        └── sub_event_type
Example: Political violence → Explosions/Remote violence → Air/drone strike

​
Usage Patterns

​
Progressive drill-down

1. get_conflict_events(days=7, country='Ukraine')
   → Returns recent conflict events in Ukraine

2. Filter by type: event_type='Explosions/Remote violence'
   → Narrows to airstrikes, shelling, IEDs

3. Drill into news: get_media_event_cluster(cluster_id=...)
   → Full news coverage for that specific event

​
Example queries

get_conflict_events(
    days=7,
    country="Ukraine",
    event_type="Explosions/Remote violence"
)

​
Common Use Cases

  • “What conflict events happened in Sudan this week?” → country='Sudan', days=7
  • “Show me airstrikes in the last 7 days” → sub_event_type='Air/drone strike', days=7
  • “List protests with civilian casualties” → disorder_type='Demonstrations', civilian_targeting=True
  • “What battles happened in Ukraine yesterday?” → country='Ukraine', event_type='Battles', days=1
  • “Show events where civilians were targeted” → civilian_targeting=True
  • “Find events about rebel advances and territorial control” → search='rebel advance territorial control', days=30
  • “What happened with protests and government crackdowns?” → search='protest crackdown security forces response'

get_media_events

Discover news story clusters — use to find stories related to conflict

get_media_event_cluster

Deep-dive into a cluster using the cluster_id from conflict event results

​
ACLED Methodology

Conflict events are coded using the ACLED methodology. Key principles:
  • One event = one day + one location + one actor interaction
  • Actor types: State forces, Rebel groups, Political militias, Identity militias, Rioters, Protesters, Civilians, External/Other forces
  • Fatalities: Conservative estimate — lowest reported figure
  • Civilian targeting: Only set when civilians are the primary target, not incidental collateral
  • Confidence score: AI coding confidence 0–1; lower values indicate ambiguous sources