This page is the DICTIONARY. It says what each code MEANS — the definition the coder applies,
and what the code includes and excludes — so you can decide whether it is the right one. For the
full value list and how the codes nest, use the
complete event taxonomy.
GET /api/v2/events?family=conflict&category=<event_type>&subcategory=<sub_event_type>. The pair is validated together, so an impossible combination returns 400 rather than an empty 200. The containment tree and the full value lists are in Complete event taxonomy.
Codes are a published contract. A code string is in the warehouse and in customer queries, so codes are added and deprecated — never renamed. Filtering on one is safe to hard-code.
Battles
Armed combat between organized armed groups, filed under the ‘Political violence’ disorder type. Covers the three ways a two-sided engagement resolves: no confirmed change of control (Armed clash), state forces retaking an area (Government regains territory), and a non-state actor capturing one (Non-state actor overtakes territory). Battles ranks FIRST in the event-type precedence order, so a composite engagement is coded here rather than under a lower-precedence type — ‘If a battle includes airstrikes, code as Battles (not Explosions/Remote violence).’ The two territorial sub-types carry an additional scope condition: ‘Only code Government regains territory or Non-state actor overtakes territory when the article clearly states control changed hands. A raid, incursion, or temporary entry does NOT qualify.‘Government regains territory
state forces retake an area previously controlled by non-state actors; confirmed control change required.
Does not cover
- A raid, incursion, or temporary entry does NOT qualify.
goldstein_scale -9.5 · quad_class Material Conflict
Non-state actor overtakes territory
an armed group captures territory from the state or a rival armed group; confirmed control change required.
Does not cover
- A raid, incursion, or temporary entry does NOT qualify.
goldstein_scale -10 · quad_class Material Conflict
Armed clash
mutual exchange of fire between two organized armed groups; neither clearly won nor lost territory — the defining criterion is active two-sided combat.
goldstein_scale -10 · quad_class Material Conflict
Protests
Organized demonstrations, filed under the ‘Demonstrations’ disorder type. The three sub-types are separated by who used force and how much: no force at all (Peaceful protest), non-lethal control measures by security forces (Protest with intervention), and lethal force by security forces (Excessive force against protesters). The demonstrators are actor type 6 Protesters regardless of the security-force response — ‘Code demonstrators as 6 even when police respond with force — the actor type reflects the protesters’ role.’ Violence initiated by the demonstrators themselves is not coded here: that is Riots / Violent demonstration, which outranks Protests in the event-type precedence order.Excessive force against protesters
security forces use live ammunition or other lethal force directly against protesters.
goldstein_scale -9 · quad_class Material Conflict
Protest with intervention
security forces use non-lethal measures (arrests, tear gas, water cannons, rubber bullets, baton charges) to disperse or control protesters.
Also covers
- arrests
- tear gas
- water cannons
- rubber bullets
- baton charges
goldstein_scale -7.5 · quad_class Material Conflict
Peaceful protest
crowd gathers to demonstrate; no violence by protesters or security forces during the event.
goldstein_scale -6.5 · quad_class Verbal Conflict
Riots
Crowd-driven collective violence, filed under the ‘Demonstrations’ disorder type. Two sub-types, separated by who is doing the violence: demonstrators who turn violent themselves (Violent demonstration), and spontaneous violence between two civilian crowds with no organized armed-group structure on either side (Mob violence). Both are distinguished from Protests by the source of the force: where security forces are the ones using force against a demonstration, the event is a Protest sub-type instead. Riots outranks Protests in the event-type precedence order.Violent demonstration
protesters themselves initiate violence — arson, throwing projectiles, destroying property, attacking police. Not triggered by security-force action.
Also covers
- arson
- throwing projectiles
- destroying property
- attacking police
- Not triggered by security-force action.
goldstein_scale -7.5 · quad_class Material Conflict
Mob violence
spontaneous collective violence between two civilian crowds (e.g. communal clashes, vigilante mob attacks); no organized armed group structure on either side.
Also covers
- communal clashes
- vigilante mob attacks
goldstein_scale -9.5 · quad_class Material Conflict
Explosions/Remote violence
Attacks delivered from a distance, filed under the ‘Political violence’ disorder type. The six sub-types are separated by delivery mechanism: aircraft or drone, indirect fire from a position, an unattended planted device, a body-worn or vehicle-borne device carried by an attacker who intends to die, a hand-thrown or rifle-launched grenade, and a chemical or biological agent. This event type ranks BELOW Battles in the event-type precedence order — ‘If a battle includes airstrikes, code as Battles (not Explosions/Remote violence).’ An attack that was prevented rather than delivered — a device defused, a munition intercepted, a cache seized — is not coded here at all, but as Strategic developments / Disrupted weapons use, because nothing detonated and nobody was attacked.Chemical weapon
a chemical or biological agent is used as a weapon (nerve agent, chlorine, mustard gas).
Also covers
- nerve agent
- chlorine
- mustard gas
goldstein_scale -10 · quad_class Material Conflict
Air/drone strike
aerial bombardment by fixed-wing aircraft or drone; no confirmed ground combat exchange.
Does not cover
- If a battle includes airstrikes, code as Battles (not Explosions/Remote violence).
goldstein_scale -9.5 · quad_class Material Conflict
Suicide bomb
attacker uses a body-worn, vehicle-borne, or hand-delivered device with intent to die in the blast.
goldstein_scale -10 · quad_class Material Conflict
Shelling/artillery/missile attack
indirect fire using artillery, rockets, mortars, cruise missiles, or ballistic missiles, without close-quarters ground engagement.
Also covers
- artillery
- rockets
- mortars
- cruise missiles
- ballistic missiles
goldstein_scale -10 · quad_class Material Conflict
Remote explosive/landmine/IED
an unattended device (planted mine, roadside IED, booby trap) detonates; not a suicide attack. Distinguish from shelling by the absence of direct or indirect fire from a position.
Also covers
- planted mine
- roadside IED
- booby trap
- not a suicide attack
- Distinguish from shelling by the absence of direct or indirect fire from a position.
goldstein_scale -8 · quad_class Material Conflict
Grenade
a hand-thrown or rifle-launched grenade is used. Small-scale and hand-delivered — distinguish from a planted IED (unattended device) and from shelling (indirect fire from a position).
Does not cover
- distinguish from a planted IED (unattended device) and from shelling (indirect fire from a position)
goldstein_scale -8 · quad_class Material Conflict
Violence against civilians
Unilateral violence by an armed or politically conflictual actor against unarmed non-combatants, filed under the ‘Political violence’ disorder type. Civilians are actor type 7 and are ‘Always assigned to actor2 / inter2 in Violence against civilians events.’ The three sub-types are separated by outcome: killing or targeted assassination (Attack), non-lethal taking or detention (Abduction/forced disappearance), and rape or other sexual violence (Sexual violence). State-force killings qualify only as political repression or conflict targeting — ‘Police or state-force killings belong in Violence against civilians only when the article clearly shows intentional political repression or conflict targeting, such as security forces firing on demonstrators, massacring detainees, or targeting civilians as suspected opponents. Ordinary line-of-duty police shootings, anti-crime raids, gang-firefight casualties, or suspects/civilians killed during routine criminal enforcement do not belong in ACLED.’ This event type ranks below Battles and Explosions/Remote violence in the event-type precedence order.Sexual violence
rape or other sexual violence inflicted on civilians by an armed or politically conflictual actor.
goldstein_scale -10 · quad_class Material Conflict
Attack
unilateral lethal or sexual violence by an armed or politically conflictual actor against civilians, or targeted assassination of a named individual in conflict/political violence context. Ordinary criminal homicide or assault does not belong here.
Does not cover
- Ordinary criminal homicide or assault does not belong here.
- Ordinary line-of-duty police shootings, anti-crime raids, gang-firefight casualties, or suspects/civilians killed during routine criminal enforcement do not belong in ACLED.
goldstein_scale -9 · quad_class Material Conflict
Abduction/forced disappearance
non-lethal taking or detention of a person by an armed actor; use only when the person is not killed (if killed, code as Attack instead).
Does not cover
- use only when the person is not killed (if killed, code as Attack instead)
goldstein_scale -9 · quad_class Material Conflict
Strategic developments
Concrete, confirmed developments that change the conflict landscape, filed under the ‘Strategic developments’ disorder type. Stated by the coder prompt: ‘STRATEGIC DEVELOPMENTS — the sub-types below are the ONLY ones this event type has. They are where the two most common mis-codings land, so read them carefully. The defining feature of the whole category is that NO violence occurred (or none beyond the act described).’ Concreteness is a scope condition, not a preference: ‘IN-SCOPE STRATEGIC DEVELOPMENTS must be concrete and confirmed: a named person arrested, a military base formally established or a force confirmed deployed, a peace agreement signed, a weapons cache confirmed seized or disrupted. A threat, warning, or press statement alone is NOT codeable.’ This event type ranks LAST in the event-type precedence order, so any co-occurring violence outranks it.Agreement
conflict actors conclude a ceasefire, peace deal, prisoner exchange, surrender, or other formal agreement.
Also covers
- ceasefire
- peace deal
- prisoner exchange
- surrender
goldstein_scale 8 · quad_class Material Cooperation
Arrests
state or state-affiliated forces detain a politically significant individual (a rebel/militia leader, a political figure) or carry out politically significant mass detentions. Ordinary criminal arrests are not ACLED at all.
Does not cover
- Ordinary criminal arrests are not ACLED at all.
goldstein_scale -5 · quad_class Material Conflict
Change to group/activity
an armed group forms, splits, merges, changes leadership, announces an alliance, mobilizes, or recruits.
goldstein_scale -7 · quad_class Material Conflict
Disrupted weapons use
an attack was PREVENTED or did NOT happen — a bomb defused, a weapons or explosives cache seized, a drone or missile intercepted/shot down, a plot foiled, an arms shipment interdicted. CRITICAL: nothing detonated and nobody was attacked, so this is NOT “Explosions/Remote violence”. If ordnance actually struck a target, it is an Explosions/Remote violence sub-type instead.
Also covers
- a bomb defused
- a weapons or explosives cache seized
- a drone or missile intercepted/shot down
- a plot foiled
- an arms shipment interdicted
- If ordnance actually struck a target, it is an Explosions/Remote violence sub-type instead.
goldstein_scale -7 · quad_class Material Conflict
Headquarters or base established
an armed group sets up a base, headquarters, or durable presence in an area.
goldstein_scale -7.2 · quad_class Material Conflict
Looting/property destruction
property is seized or destroyed OUTSIDE of a battle — e.g. after a group takes control of an area. If it happened during an armed clash, code the clash.
Does not cover
- If it happened during an armed clash, code the clash.
goldstein_scale -9.5 · quad_class Material Conflict
Non-violent transfer of territory
territory changes hands WITHOUT fighting (a negotiated withdrawal, a handover).
Also covers
- a negotiated withdrawal
- a handover
goldstein_scale 7 · quad_class Material Cooperation
Other
a politically significant strategic development that fits none of the above and involved no violence. “Other” exists ONLY under Strategic developments — never use it to describe a violent event whose sub-type you are unsure of. If violence occurred, pick the violent sub-type that the text supports.
Does not cover
- never use it to describe a violent event whose sub-type you are unsure of. If violence occurred, pick the violent sub-type that the text supports.
goldstein_scale -2 · quad_class Verbal Conflict