Skip to main content

​
Overview

get_conflict_events_summary returns aggregated totals and bucketed counts for ACLED-coded conflict events. It is the broad-and-shallow counterpart to get_conflict_events — designed to understand the shape, scale, and distribution of a conflict situation before fetching individual event records. Results include a totals object (aggregate across the entire filter) and a buckets array (one row per group_by dimension value).

​
Progressive Disclosure Pattern

1. get_conflict_events_summary(region='Middle East', days=7, group_by='country')
   → Which countries have the most events? (ranked by event_count desc)

2. get_conflict_events_summary(country='Sudan', days=7, group_by='event_type')
   → What types of violence? (Battles, Protests, Airstrikes, etc.)

3. get_conflict_events(country='Sudan', event_type='Battles')
   → Individual battle events with actors, locations, and fatalities

​
Parameters

ParameterTypeDefaultDescription
group_byenumdateDimension to group results by. See values below.
daysinteger7Lookback window in days from date. Max 90.
datestringtoday UTCAnchor/end date in YYYY-MM-DD format.
countrystring—Full English country name (e.g. 'Sudan', 'Ukraine', 'Gaza Strip'). Same format as get_conflict_events.
regionenum—Geographic ACLED region. Expands to all countries in the region. Only one region per request. See valid values below.
disorder_typeenum—Top-level disorder: Political violence, Demonstrations, or Strategic developments.
event_typeenum—ACLED event type. See values below.
sub_event_typeenum—Most specific classification (e.g. Air/drone strike, Armed clash, Peaceful protest). See full enum below.
fatalitiesboolean—If true, only include events with reported fatalities > 0.
civilian_targetingboolean—If true, only include events where civilians were the primary target.

​
group_by Values

ValueDescription
dateOne bucket per day, ascending. Use for trend lines over time.
countryOne bucket per country, ordered by event_count desc. Includes centroid lat/lon for map rendering.
event_typeACLED event types (Battles, Protests, Riots, etc.).
disorder_typeTop-level disorder classification (Political violence, Demonstrations, Strategic developments).
regionACLED geographic regions.

​
region Values

Western Africa, Middle East, Eastern Africa, Southern Asia, East Asia, Eastern Europe, Latin America & Caribbean, South-Eastern Asia, Northern America, Western Europe, Central Asia, Oceania, Middle Africa, Northern Africa, Southern Africa, Caribbean, Central America

​
event_type Values

ValueDescription
BattlesArmed clashes, territorial fights between organized groups
ProtestsDemonstrations, marches, excessive force against protesters
RiotsViolent demonstrations, mob violence
Explosions/Remote violenceAirstrikes, drones, shelling, IEDs, bombs
Violence against civiliansAttacks, abductions, sexual violence targeting civilians
Strategic developmentsAgreements, arrests, base establishment, looting

​
sub_event_type Values

Government regains territory, Non-state actor overtakes territory, Armed clash
Excessive force against protesters, Protest with intervention, Peaceful protest
Violent demonstration, Mob violence
Chemical weapon, Air/drone strike, Suicide bomb, Shelling/artillery/missile attack, Remote explosive/landmine/IED, Grenade
Sexual violence, Attack, Abduction/forced disappearance
Agreement, Arrests, Change to group/activity, Disrupted weapons use, Headquarters or base established, Looting/property destruction, Non-violent transfer of territory, Other

​
Data Structure

{
  "success": true,
  "group_by": "country",
  "totals": {
    "event_count": 847,
    "fatalities": 1203,
    "fatality_events": 312,
    "civilian_targeting_events": 89,
    "countries_affected": 14,
    "event_types_active": 5,
    "regions_active": 3,
    "avg_confidence": 0.81,
    "centroid_lat": 24.1,       // only when country or region filter active
    "centroid_lon": 38.7
  },
  "buckets": [
    {
      "country": "Sudan",
      "event_count": 214,
      "fatalities": 388,
      "fatality_events": 97,
      "civilian_targeting_events": 23,
      "countries_in_bucket": null,  // omitted when group_by=country
      "avg_confidence": 0.79,
      "centroid_lat": 15.6,
      "centroid_lon": 32.5
    }
  ],
  "filters": { "region": "Middle East", "days": 7 },
  "metadata": { "bucket_count": 14, "execution_time_ms": 42 }
}

​
Caching

  • Historical queries (date before today UTC): cached 24 hours
  • Live queries (includes today): cached until 7 minutes past the next UTC hour (aligned to hourly ingestion)

​
Example Queries

get_conflict_events_summary(
    region="Middle East",
    days=7,
    group_by="country"
)
# → Which countries had the most conflict events this week?

​
Common Use Cases

  • “How many conflict events happened in the Middle East this week?” → region='Middle East', days=7, group_by='country'
  • “Show me daily trends for airstrikes in Sudan” → country='Sudan', sub_event_type='Air/drone strike', days=30, group_by='date'
  • “Which countries in Africa had the most violence?” → region='Eastern Africa', days=30, group_by='country'
  • “What types of events happened in Gaza?” → country='Gaza Strip', days=7, group_by='event_type'
  • “Protest trends over the past month” → event_type='Protests', days=30, group_by='date'
  • “How many civilian targeting events in the past week?” → civilian_targeting=True, days=7, group_by='country'

get_conflict_events

Individual conflict event records — the drill-down step after this summary

get_cameoplus_events_summary

Aggregate summary for CAMEO+ non-conflict events

get_media_events

News story clusters linked to conflict events via cluster_id