ACLED API tutorial: fetch and visualize conflict data for humanitarian analysis

Why the ACLED API matters for humanitarian analysis

ACLED codes political-violence and protest events across more than 240 countries and territories, with each record carrying a date, location, actor, event_type, and fatality estimate. Programmatic access through the read API lets humanitarian teams monitor escalation, feed alerting systems, and integrate conflict signals into needs assessments without waiting for monthly PDF bulletins.

This tutorial focuses on the two fields most relevant to protection and response planning: event_type (the typology of violence) and fatalities (a conservative lower bound on reported deaths). The examples use Sudan in the first half of 2026, but the pattern generalises to every country ACLED covers.

curl: a single filtered pull

curl -G "https://api.acleddata.com/acled/read" \
  --data-urlencode "key=YOUR_KEY" \
  --data-urlencode "email=you@example.org" \
  --data-urlencode "country=Sudan" \
  --data-urlencode "event_type=Battles|Violence against civilians" \
  --data-urlencode "event_type_where=IN" \
  --data-urlencode "event_date=2026-01-01|2026-06-30" \
  --data-urlencode "event_date_where=BETWEEN" \
  --data-urlencode "limit=500"

Python: paginate and aggregate by event_type

import requests
import pandas as pd

API_KEY = "YOUR_KEY"
EMAIL   = "you@example.org"

params = {
    "key": API_KEY,
    "email": EMAIL,
    "country": "Sudan",
    "event_date": "2026-01-01|2026-06-30",
    "event_date_where": "BETWEEN",
    "event_type": "Battles|Violence against civilians|Explosions/Remote violence",
    "event_type_where": "IN",
    "limit": 5000,
    "page": 1,
}

rows = []
while True:
    r = requests.get("https://api.acleddata.com/acled/read", params=params, timeout=60)
    r.raise_for_status()
    batch = r.json().get("data", [])
    if not batch:
        break
    rows.extend(batch)
    params["page"] += 1

df = pd.DataFrame(rows)
df["fatalities"] = pd.to_numeric(df["fatalities"], errors="coerce").fillna(0)

# Aggregate by event_type
by_type = df.groupby("event_type").agg(
    events=("event_id_cnty", "count"),
    fatalities=("fatalities", "sum"),
).sort_values("fatalities", ascending=False)

print(by_type)

Requires requests and pandas. Replace YOUR_KEY and you@example.org with the credentials issued by ACLED. The loop stops when a page returns no further records.

• Stacked bar by month. Group by month and event_type, then stack Battles, Violence against civilians, and Explosions/Remote violence to see whether escalation is driven by frontline combat or civilian targeting.
• Choropleth by admin1. Sum fatalities per province over the window, and shade regions by intensity. Overlay event points sized by fatalities for context.
• Actor network. Build an edge list from actor1 and actor2 to visualise which parties are engaged in the most lethal incidents.
• Trend with rolling mean. Plot weekly event counts and fatalities with a 4-week rolling mean to smooth reporting noise.