ACLED Conflict Events: Intelligence Source Guide

ACLED codes individual political violence and protest events – date, place, actors, sub-event type and a conservative fatality figure – from media and partner reporting across most of the world, and releases weekly. It is the default event layer for conflict analysis, including abduction and forced disappearance, and its biases are entirely inherited from what gets reported.

At a glance

Source	ACLED Conflict Events
Category	Conflict, Crime & Human Security › Organised Crime, Gangs & Piracy
Homepage	https://acleddata.com/
Machine interface	`https://api.acleddata.com/acled/read`
Format	`JSON`
Access	Free registration — API key at no cost
Disciplines	Open Source Intelligence, Geospatial Intelligence, News Intelligence
Mission domains	Kidnap, Hostage & Extortion, Conflict & Humanitarian, Military & Defense

Geocoded political-violence & kidnapping events. — as catalogued in the platform’s own source registry.

The Armed Conflict Location and Event Data Project is a coded event dataset. Analysts read media reporting, partner organisation output and local observatory material, and turn each discrete incident of political violence, demonstration or strategically significant development into a structured row: a date, a country and a nested administrative hierarchy, a named location with coordinates, one or two named actors plus associated actors, an event type and a more specific sub-event type, a civilian targeting flag, a fatality count, an explanatory note in free text, and metadata recording which sources were used and at what geographic scale they operate. Two precision fields qualify the whole record – one for how exactly the date is known, one for how exactly the location is known – and they are the most important fields in the schema for anyone doing serious work. The taxonomy distinguishes battles, explosions and remote violence, violence against civilians, protests, riots, and strategic developments, and within violence against civilians it separately codes attacks, sexual violence, and abduction or forced disappearance, which is the primary route into kidnap analysis. Data is released weekly and is available through a downloadable export interface, curated regional files and a programmatic interface for registered users.

The analytical job ACLED does that nothing else does at this scale is to give conflict a spatial and temporal grain fine enough to be joined to anything else. Casualty aggregates tell you a war is happening; ACLED tells you which district, on which day, with which actor, doing what. That is what makes it the connective tissue between OSINT, GEOINT and NEWSINT workflows: an equipment loss with no date can be anchored against events in the same place, a displacement figure can be attributed to a specific sequence of attacks, a supply route hypothesis can be tested against whether fighting actually occurred where the route runs. Its second distinctive property is that it codes non-lethal and non-violent activity – protests, riots, arrests, base establishment, agreements, disrupted weapons use – so it captures the political and organisational activity that precedes and follows violence rather than only the violence itself. For kidnap and extortion work specifically, the abduction and forced disappearance sub-event type provides something close to the only systematic cross-national event-level record of politically motivated abduction that exists in the open, with the important qualification that ACLED is a political violence dataset and not a crime dataset.

Who publishes it, and why that matters

ACLED is an independent non-profit organisation with a founder-led research lineage, funded through a mix of government and institutional grants, partnerships and, increasingly, commercial licensing of the data it makes free for non-commercial users. That hybrid model has consequences you should understand rather than resent. It has funded a genuinely remarkable expansion from a single-region academic project to near-global weekly coverage, which no purely grant-funded effort would have sustained. It also means the access terms are actively managed and have changed more than once, including a migration of the programmatic interface and a tightening of the boundary between free research use and commercial use. The organisation is transparent about methodology, publishes a detailed codebook, revises historical data when errors are found, and states its own limitations more clearly than most producers. It also operates in politically contested space, and its coding decisions about actor names, conflict classification and event attribution are regularly challenged by governments and by parties to the conflicts it covers. That contestation is a normal condition of the work and not in itself a reliability signal in either direction.

Provenance is the first question to ask of any dataset and the one most often skipped. Who collects it, what their incentive is, whether they publish a methodology, and whether they correct the record when they get something wrong all bear directly on how much weight a finding drawn from it can carry.

What a record actually contains

The fields you will be working with, what each one means, and whether it is something you can pivot on. Read the meanings carefully — more analysis is wrecked by misreading a field than by failing to find one, and a field that looks like an observation is often an inference.

Field	Type	What it means	Pivot value
`event_id_cnty`	string	The country-scoped event identifier. It is stable for an unmodified event but events are merged, split and deleted during ongoing review, so it is not a permanent key across snapshots.	Your own snapshot archive, which is the only place a deleted event still exists.
`event_date`	timestamp	The date the event occurred, to the day. Multi-day operations are coded as separate daily events, so an offensive lasting a week produces several rows rather than one.	Alignment with any other dated source; the basis of all tempo analysis.
`time_precision`	enum	How exactly the date is known: the exact day, a known week coded to a representative day, or only a known month. Ignoring this field turns coding conventions into apparent clustering on particular dates.	None, but it gates every daily-resolution claim you might make.
`event_type`	enum	The top-level category: battles, explosions and remote violence, violence against civilians, protests, riots, or strategic developments. The last of these is not violence and must not be summed into violence totals.	Sub-event type for the analytically useful granularity.
`sub_event_type`	enum	The specific form of the event – armed clash, air or drone strike, shelling, remote explosive or landmine, suicide bombing, attack on civilians, sexual violence, abduction or forced disappearance, peaceful protest, mob violence, arrests, and others. This is the field most analysis should actually filter on.	Weapon and tactic analysis; the abduction sub-event is the entry point for kidnap work.
`actor1 / actor2`	string	The named primary parties, drawn from a maintained actor list with standardised naming. Naming is a coding decision, groups fragment and rename, and cross-time actor analysis requires reconciling those changes yourself.	Actor profiles, organisational lineage, and other events involving the same or successor names.
`assoc_actor_1 / assoc_actor_2`	string	Associated actors, including affiliated groups, ethnic or communal identifiers and named units. Frequently the most informative field for understanding who was actually involved and routinely discarded in analysis.	Network construction between groups and their affiliates.
`actor_type_codes`	enum	Categorical classification of each actor – state forces, rebel groups, political militias, identity militias, rioters, protesters, civilians, external forces – which permits analysis by actor class rather than by name.	Interaction analysis: which classes of actor are fighting which, which is often more stable than named-group analysis.
`civilian_targeting`	enum	A flag indicating that civilians were the target of the event, applied across event types rather than only within violence against civilians. Essential for protection of civilians analysis and easy to miss.	Protection reporting, displacement data and human rights documentation.
`latitude / longitude`	int	Coordinates for the coded location. These are the location's coordinates, not the incident's, and for less precisely known events they may be an administrative centre rather than where anything happened.	Spatial joins with terrain, infrastructure, control maps and other geolocated sources – subject to the precision field.
`geo_precision`	enum	Whether the coordinates represent a named specific location, the nearest town to a somewhat known area, or only the administrative region coded to a representative point. The third case produces heavy artificial clustering at provincial capitals.	None, but it determines whether any spatial analysis you perform is meaningful.
`fatalities`	int	The most conservative available estimate of deaths, taken from reporting. ACLED itself flags this as the least reliable field in the dataset, and figures are frequently contested, revised, or unavailable and coded as zero rather than unknown.	Casualty-specific sources; never treat as a measurement without corroboration.
`source / source_scale`	string	Which outlets or organisations reported the event and whether they operate at local, subnational, national, regional, international or other scale. This is your only handle on reporting bias and it is present on every row.	Media environment analysis; weighting of coverage density by source availability.
`notes`	string	Free-text description of the event as coded. Contains the specificity that the categorical fields compress, including named places, units, circumstances and the coder's reading of contested details.	Everything qualitative. Search this field before concluding that something is absent from the dataset.

Coverage — and what is not in it

Coverage is now close to global but the panel is unbalanced, and this is the property most often overlooked. The project began with Africa from the late 1990s and expanded region by region over two decades, reaching worldwide coverage relatively recently, which means the start date differs by country and any cross-national time series is truncated at different points for different places. Within its coverage window ACLED codes political violence, demonstrations and strategic developments from a mixture of international wire and press reporting, national and local media in many languages, partner organisations and local conflict observatories, and verified new-media reporting. Release is weekly, covering events through a recent cutoff, with historical data under continuous review and revision. The unit of coverage is the event, defined as a discrete action by named actors in a specific place on a specific day, so extended operations decompose into multiple rows and the event count is not an incident count in the ordinary-language sense. Spatially the data resolves to named locations where reporting permits and to administrative centres where it does not, with the precision field disclosing which. Temporally it resolves to the day where reporting permits and to a week or month otherwise, again with a disclosing field.

Known blind spots

Absence of evidence here is not evidence of absence. These are the conditions under which ACLED Conflict Events will not show you something that is nevertheless real:

Nothing enters the dataset unless someone reported it. Areas under information blackout, without press presence, without connectivity or under effective repression of reporting produce fewer events regardless of how much violence occurs there.
The panel is unbalanced across time. Because coverage expanded region by region over two decades, a global time series will show apparent increases in violence that are purely artefacts of new countries entering the dataset.
ACLED is a political violence dataset and not a crime dataset, so ordinary criminal kidnapping, extortion and gang activity without a political dimension are outside scope or captured only partially, which limits the abduction data for pure kidnap-for-ransom analysis.
Fatality figures are the weakest field by the producer's own account. They reflect the most conservative reported estimate, are often unavailable, are contested by parties to the conflict, and are revised, so any analysis resting primarily on death counts is resting on the softest data in the file.
Coordinates at the lowest precision level are administrative centres rather than incident locations, which creates dense artificial clusters at provincial capitals that will appear in any heatmap as hotspots that are actually coding conventions.
Strategic developments are not violence. They are included because organisational and political activity matters, and summing them into violence totals – which happens constantly in secondary analysis – inflates conflict measures with arrests, agreements and base establishments.
Actor naming is a coding judgement applied to entities that fragment, merge, rename and deny their own existence, so longitudinal actor analysis requires reconciliation work the dataset does not do for you.
Historical data is revised continuously, so two snapshots taken weeks apart will disagree about the past, and any published figure without a snapshot date is unreproducible.
Event counts are sensitive to how reporting granularity maps onto the event definition, so a well-covered conflict can produce more events than a worse one simply because journalists filed separately about each engagement.

Write the blind spot into the product. A statement that something “was not observed in ACLED Conflict Events” is defensible; a statement that it “did not happen” is not, and the difference is what survives cross-examination.

Access, licensing and what you may do with it

Access model: Free registration — an account or API key, at no cost

Access requires registration and the arrangements have changed. The long-standing programmatic read endpoint authenticated by an email and key pair has been superseded by an account-and-token model, and the practical instruction is to consult ACLED's current access and API documentation before writing any client, rather than reusing a code sample from an older project. Alongside the programmatic route there is a web export interface for building filtered downloads and a set of curated regional data files intended for bulk use, which are usually the right choice for anything historical because they are assembled for consistency. For weekly operational tracking, an incremental pull filtered by country and date range is the appropriate pattern, with the whole-history file refreshed periodically to pick up revisions to older events. Register with an institutional address, read the terms attached to your access tier before building anything on it, and record the retrieval timestamp with every extract you keep.

Licence

ACLED makes the data available free for non-commercial use under its published terms, with attribution required in any product that uses it, and requires a licence agreement for commercial use. The commercial boundary is real and is enforced: incorporating the data into a paid product or service, or using it to deliver client work for a fee, generally falls on the commercial side, and organisations should resolve this before deployment rather than after. Attribution is not a courtesy here; it is a term of use, and it should name ACLED and the access date. The terms have been revised over time as the organisation's funding model evolved, so confirm the current text rather than relying on an internal note written when your pipeline was built. Redistribution of the raw data is restricted, which affects any plan to share extracts with partners or to publish a derived dataset, and derived aggregates occupy a grey area worth clarifying directly with ACLED if your use is substantial.

Rate limits and fair use

Practical throughput is governed by pagination and by the terms of your access tier rather than by any single published number, and the current documentation is the authority. Design for restraint: pull incrementally by date range and country rather than re-downloading history every cycle, use the curated files for bulk historical needs instead of paging through the interface, cache locally and serve internal queries from your own copy. Weekly release means anything more frequent than a daily pull is wasted effort. Back off on errors rather than retrying tightly, identify your client, and remember that this is a non-profit serving a large research community, so an inefficient pipeline is taking capacity from someone doing fieldwork.

Licensing changes, and it changes without warning. A dataset that was free for research this year may not be free for commercial or evidential use next year. Confirm the current terms before you build a dependency on it, and record the terms you relied on alongside the data — the licence in force at the time of collection is part of the provenance.

Collecting it

How ACLED Conflict Events is actually pulled, in the order you would set it up. Prefer the bulk or export interface over per-item lookups wherever one exists: it is kinder to the publisher, faster for you, and gives a reproducible snapshot rather than a series of point-in-time answers you cannot reconstruct later.

Method	Format	Cadence	Notes
Incremental API pull	JSON	weekly, aligned to the release	The operational method. Filter by country and event date range, page through results, and store raw responses. Confirm the current authentication model before building, because it has changed.
Curated regional data files	CSV	periodic refresh	The right choice for historical baselines and for rebuilding after revisions. Assembled for internal consistency and far less wasteful than paging the whole history through an interface.
Filtered web export	CSV	ad hoc	Convenient for a single question or a one-off product. Record the filter parameters and retrieval date, because the same filter will return different rows next month.
Full-history refresh	bulk	monthly or quarterly	Necessary because historical events are revised, merged and deleted. Without a periodic full refresh your archive slowly diverges from the source in ways nothing will alert you to.
Snapshot retention	bulk	every collection	Keep each pull with its timestamp. Continuous revision means the archive is the only way to explain why a figure you published no longer matches the live data.
Derived product ingestion	HTML	as published	ACLED's own index and analytical outputs summarise what its analysts consider significant, which is a useful check on whether your automated reading of the data matches the producer's.

Ingesting it into the platform

Every step below is idempotent and cursor-based: interrupt one and it resumes from where it stopped rather than duplicating rows or losing progress. Collection is recorded per source, so a feed that quietly stops publishing shows up as a stale timestamp instead of silently thinning your coverage.

Register with terms recorded — Add ACLED in sources.php with the access tier, the attribution requirement and the commercial-use boundary recorded as source properties, so that any downstream export inherits the licensing constraint rather than discovering it at publication.
Schedule the weekly pull — Configure collect.php to run an incremental fetch aligned to the release rhythm, with cron.php owning retries and alerting. Silent collection failure looks identical to a quiet week, which is the worst possible failure mode for a conflict feed.
Preserve precision fields as structure — Import through import.php with time precision and geo precision as first-class attributes on every event, so that maps and timelines can degrade gracefully rather than presenting a centroid-coded provincial estimate as a pinpoint.
Resolve actors to entities — Push actor and associated actor names through resolve-everything.php into canonical actor entities visible on actor-profile.php, maintaining alias and successor mappings so that fragmentation and renaming do not break longitudinal analysis.
Place events geographically — Load coordinates into the geospatial layer for use in link-analysis.php and theater.php, carrying the precision level through to rendering so that low-precision events are visually distinguishable from located ones.
Build the temporal spine — Feed events into timeline.php as the dated backbone that undated sources are anchored against, which is the single highest-value integration this dataset supports across the rest of the catalogue.
Correlate across the catalogue — Use correlate.php to associate events with equipment loss documentation, weapons recoveries, displacement reporting and media event data for the same place and period, and surface abduction sub-events into the kidnap and extortion view.
Run alerting on defined patterns — Configure alerts.php against explicit criteria – sub-event type, actor class, administrative area, civilian targeting – rather than on raw event volume, since volume moves with reporting density and will generate alerts about journalism rather than about violence.
Attribute on export — Ensure export.php and reports.php emit the required ACLED attribution and the snapshot date with any product. The Summarise skill writes prose about coded events that already exist; it does not code, geolocate or attribute any event.

Registered sources and their last-collected state are listed in sources.php, and the scheduled chain that keeps them current is in automation.php.

How it is wrong, and how to tell

Every dataset is wrong in characteristic ways. Knowing which ways is the difference between using a source and being used by one, and it is the part of source evaluation most often skipped because it is the part that takes work.

ACLED is the best available open event dataset for most of the world and it is a media-derived product, and both halves matter. The coding is done by trained analysts against a published codebook, sourcing is recorded on every row, precision is disclosed rather than assumed, and the organisation revises errors and publishes methodological changes. That places it far above any automated event extraction system in accuracy and interpretability. The limits are inherited from the input: events are known only if reported, reporting density varies enormously with press freedom, connectivity, language and international interest, and no amount of careful coding corrects a systematic absence in the source material. Within that constraint, the fields differ sharply in reliability. Event occurrence, date to the disclosed precision, country and event type are strong. Sub-event type and actor identification are good but involve judgement that reasonable coders can differ on. Location is as good as the precision field says it is. Fatalities are weak and the producer says so. The right posture is to treat the dataset as a high-quality record of what was reported, not as a census of what occurred, and to make that distinction explicit whenever a count leaves your organisation.

Characteristic false positives

Reading event volume as violence intensity. Volume tracks reporting density, so a country where the press can operate will out-report a country where it cannot, and comparing them directly measures journalism rather than conflict.
Mapping low-precision events as though they were located. Centroid coding produces dense clusters at administrative capitals, and a heatmap built without filtering on geographic precision will confidently identify hotspots that are coding artefacts.
Summing strategic developments into violence totals. Arrests, agreements, base establishments and non-violent territorial transfers are coded because they matter analytically, not because they are violence, and including them inflates every conflict metric.
Treating fatality counts as measurements. They are conservative reported estimates, frequently absent and coded as zero, frequently contested, and frequently revised, and an analysis whose conclusion depends on them is resting on the weakest field in the file.
Building a global trend line across the unbalanced panel, which produces an apparent secular increase in world violence that is substantially the arrival of new countries into coverage.
Analysing named actors longitudinally without reconciling fragmentation, renaming and merger, which silently splits one organisation into several or fuses several into one depending on the coding conventions in force.
Comparing snapshots without recording dates. Continuous revision of historical data means the same query returns different results over time, and an unexplained discrepancy between two internal reports is usually this rather than an error.
Reading the abduction sub-event as a complete kidnap picture. It captures politically motivated abduction and forced disappearance as reported; ordinary criminal kidnap for ransom is largely outside the dataset's scope and its absence is not evidence of a low rate.

None of these make the source unusable. They make it a source that requires corroboration before an assertion built on it goes into a product, which is true of every source and admitted by few.

Ageing

Two clocks run here in opposite directions. Forward, the most recent week is the thinnest, because reporting on events continues to surface for days and weeks after they occur, so the latest data is systematically incomplete and will fill in. An analyst who compares last week against the week before will reliably find a decline that does not exist. Backward, historical data is under continuous review, so old events are corrected, merged, split and occasionally deleted, and your archive diverges from the live dataset a little more every week unless you periodically refresh the whole history. The analytical currency of an event decays at the speed of the conflict: a battle six months ago constrains the current picture strongly in a static front and barely at all in a fluid one. A stale record in this source looks like an event whose identifier no longer exists upstream, a fatality figure that has since been revised, an actor name that has been superseded by a successor entity, or a recent-week count that was quoted before it filled in and now understates by a third.

What this source feeds

A source is only worth what it lets you conclude. These are the disciplines that collect through it, the mission domains it serves and the data points it yields — every one is a tag, so you can follow any thread from here into the rest of the library.

Collected by these intelligence disciplines

Serves these mission domains

Yields these data points

How each sector uses ACLED Conflict Events

The same dataset is worked very differently depending on who you are, what authority you hold, and what you are ultimately producing. A military analyst is supporting a commander’s decision; a journalist is meeting a publication standard; an NGO caseworker is protecting a person. The records are shared — the constraints, thresholds and outputs are not.

🎖 Military and defence

For theatre understanding and pattern-of-life work this is the standard open baseline, giving daily-resolution activity by location and actor class across a whole area of operations. It supports tempo analysis, identification of contested versus quiet districts, characterisation of adversary tactics through sub-event types such as remote explosive use or air and drone strikes, and the temporal anchoring of intelligence from sources that carry no date. Planners should filter on geographic precision before any spatial product reaches a briefing, because centroid clustering will otherwise be read as concentration of activity. Treat the dataset as a reported-activity layer to be reconciled against organic reporting, not as a substitute for it, and never present event counts as a measure of enemy strength.

🕵 National intelligence

For indications and warning this is the most useful open event layer available, and its value comes from the categorical fields rather than the totals. Shifts in the mix of sub-event types, changes in which actor classes are interacting, the appearance of civilian targeting in an area that previously saw only armed clashes, and the tempo of strategic developments such as base establishment or arrests are all leading signals that raw volume obscures. The source and source scale fields give you a direct handle on reporting bias, which is the single most important control in any cross-country comparison. Combine with equipment documentation, displacement data and media event streams, and be explicit in every assessment about the difference between what was reported and what occurred.

👮 Law enforcement

For law enforcement the strongest use is in the abduction and forced disappearance sub-event type, in mob violence and communal violence coding, and in the organised armed group activity that sits at the boundary between political violence and organised crime, which is where much kidnap and extortion activity in practice lives. The critical limitation must be understood first: this is a political violence dataset, so ordinary criminal kidnapping is largely out of scope and the data cannot support prevalence claims about kidnap for ransom. Use it to establish the environment, identify armed groups active in a district and build the pattern context around a case; use national crime statistics and case data for the crime picture itself. Any live case information belongs in the mandated system, not in an open dataset workflow.

🔍 Private investigation and corporate security

For travel risk, duty of care and kidnap and ransom underwriting this is the standard open input for country and sub-national risk assessment, and its administrative hierarchy makes it directly usable for site-level judgements. It supports questions about whether a route, a district or a facility sits in an area of recorded armed activity, what kinds of incidents occur there, and how the picture has moved over the last quarter. The professional discipline is to work at the sub-event and precision level rather than from country aggregates, to state clearly that the data reflects reported political violence rather than crime, and to resolve the commercial licensing position before the data appears anywhere in a client deliverable.

📰 Journalism and OSINT media

For journalism ACLED provides the numbers that anchor conflict reporting, along with the fastest route to error. Cite the dataset and the access date, use sub-event types rather than raw totals, avoid comparing the most recent week to earlier weeks because recent data is incomplete, and do not present fatality figures as counts. The organisation publishes its own periodic analytical products which are written for exactly this purpose and carry the caveats already applied. Where a story turns on a specific incident, read the notes field and go back to the cited sources rather than reporting the coded row.

🌍 NGO, humanitarian and human rights

For humanitarian and human rights organisations the civilian targeting flag and the violence-against-civilians event type are the core, supporting protection analysis, access negotiation and the evidencing of patterns of attack for advocacy and accountability. Geographic granularity makes it usable for operational security decisions at field office level, provided precision is respected. Organisations should note that under-reporting is worst in exactly the areas where protection needs are highest, so a quiet district in the data may be an inaccessible one, and that treating an absence of coded events as an absence of violence has real consequences for where assistance goes.

🎓 University and research

This is a canonical dataset in conflict studies and the methodological expectations around it are well established: state the version and access date, address the unbalanced panel explicitly, model reporting bias rather than assuming it away, and avoid fatality-dependent designs unless the research question genuinely requires them. The continuous revision policy is a reproducibility hazard and the curated data files exist partly to mitigate it. Researchers should read the codebook properly rather than inferring the taxonomy from column values, since several categories mean something narrower than their names suggest, and should be careful when combining with other event datasets whose event definitions differ enough to make joint counts meaningless.

Playbook: working ACLED Conflict Events end to end

A repeatable sequence from first pull to finished product. Each phase states what you are trying to establish, not merely what to click — the objective is a defensible chain of reasoning, not a completed checklist.

Phase 1 — Read the codebook before the data

The taxonomy is precise and several categories mean something narrower than their names imply. Strategic developments are not violence, violence against civilians is a defined event type rather than a description, and the precision fields are not optional metadata. An hour with the codebook prevents the majority of errors that appear in published work using this dataset.

Phase 2 — Establish the coverage window for your countries

Check when each country in your analysis entered the dataset. A cross-national comparison or a long trend line across countries with different start dates will show changes that are entirely artefacts of coverage expansion, and this is the most common structural error made with ACLED.

Phase 3 — Characterise the reporting environment first

Before interpreting any count, assess press freedom, connectivity, language coverage and the presence of local partner organisations for each area of interest, using the source and source scale fields as evidence. This assessment is the control variable for everything downstream and should be written down, not held in your head.

Phase 4 — Filter on precision before you map anything

Separate events located to a named place from those coded to an administrative centre, and either exclude the latter from spatial analysis or render them distinctly. Skipping this step produces maps whose most prominent features are coding conventions, and those maps get briefed.

Phase 5 — Work at sub-event level

Build your analysis on sub-event types rather than event types or totals. The difference between an armed clash, a drone strike, a landmine detonation and an abduction is the analysis; aggregating them into a violence count discards the signal and keeps the noise.

Phase 6 — Reconcile actors into stable entities

Construct your own actor mapping that handles renaming, fragmentation, mergers and the relationship between named groups and their associated actors. Do this once, maintain it, and record the decisions, because every longitudinal claim about an organisation depends on it and reviewers will ask.

Phase 7 — Treat fatalities as a separate, weaker line

If your question needs deaths, source them deliberately and corroborate. If it does not, use event counts by type and say explicitly that you are not reporting casualties. Mixing a weak field into an otherwise sound analysis contaminates the whole product's credibility.

Phase 8 — Anchor the rest of your collection to this timeline

Use the event layer as the dated spine that undated material is registered against – equipment losses, imagery, weapons recoveries, displacement reporting. This is where ACLED delivers value that has nothing to do with counting events, and it is underused.

Phase 9 — Define alerting on patterns, not volume

Set thresholds on specific combinations of sub-event type, actor class, area and civilian targeting. Volume-based alerting fires when a news cycle turns and stays silent through an information blackout, which is precisely backwards.

Phase 10 — Refresh history, not just the present

Schedule a periodic full reload alongside the incremental pull. Continuous revision means an archive that only ever appends will drift away from the source, and the drift is invisible until someone compares your figure with the live dataset in public.

Phase 11 — Cross-validate against an independent coder

Test your picture against another organised violence dataset with a different methodology and a different event definition. Disagreement is expected and diagnostic; understanding why two datasets differ for a given conflict usually reveals something about the reporting environment that neither states directly.

Phase 12 — Publish with version, attribution and caveat

Every product should carry the ACLED attribution required by the terms, the snapshot date, the precision handling you applied and a plain statement that the data records reported events. Without the last of these, readers will treat the counts as a census, and the resulting misunderstanding will be attributed to you.

The platform ships this as a step-checked workflow in playbooks.php, so progress is recorded against a case rather than held in someone’s head.

What to pair it with

No single source carries a finding. These are the datasets that corroborate, extend or contradict this one — and a source that contradicts is worth more than one that agrees, because it is the only thing that will tell you when you are wrong.

Source	Relationship	What it adds
Uppsala Conflict Data Program	corroborates	An independently coded organised violence dataset with a different event definition, stricter inclusion criteria and a longer consistent series. The primary external validity check on any ACLED-based finding.
GDELT	extends	Machine-extracted global media event and tone data at far higher volume and far lower precision. Useful for detecting that something is being reported before it is coded, and for characterising the media environment itself.
Oryx OSINT Equipment Losses	extends	Visually confirmed materiel losses with no dates, which ACLED events can anchor temporally and spatially. The complementarity runs both ways: losses give physical substance to coded battles.
Conflict Armament Research iTrace	extends	Physically documented weapons from the same theatres, which turn an armed clash record into a question about who supplied the parties.
ReliefWeb	corroborates	Humanitarian situation reporting that frequently describes the consequences of coded events and occasionally records incidents that never reached the media ACLED reads.
Humanitarian Data Exchange	extends	Displacement, access and needs data that can be attributed to specific event sequences, turning a violence record into a humanitarian impact assessment.
SIPRI Military Expenditure Database	extends	The structural economic context in which conflict intensity is interpreted, and a common dependent or independent variable in research designs using event data.
UNODC	contradicts	Criminal justice statistics covering the ordinary crime that ACLED excludes. Essential for any kidnap or extortion question, because the political violence dataset will systematically understate the criminal picture.
Small Arms Survey	extends	Violent death data bringing conflict and non-conflict lethal violence into one frame, which is the correct context for interpreting fatality patterns in event data.

Legal, ethical and operational constraints

Use is governed by ACLED's terms, which permit free non-commercial use with mandatory attribution and require a licence for commercial use; the boundary is enforced and should be settled with ACLED before the data appears in any revenue-generating product or client deliverable. Redistribution of raw data is restricted, which constrains sharing extracts with partners and publishing derived datasets. Beyond licensing, the material itself is sensitive in ways that warrant care. Events are geolocated records of violence involving identifiable communities and, through the notes and actor fields, sometimes identifiable individuals; in jurisdictions with comprehensive data protection regimes the processing of that material needs a lawful basis and proportionality assessment like any other personal data processing. Protection-sensitive uses – anything that could expose the location of vulnerable populations, humanitarian operations or witnesses – require handling controls that go beyond the licence. And the ordinary constraint applies: this is analysis of reported violence for understanding, protection and accountability, and nothing in this library supports its use to locate, approach or target anyone.

Operational security

Access is credentialed, so every query is attributable to your organisation and the pattern of countries, actors and date ranges you request is visible to the operator and to anyone with lawful access to those logs. For most users this is unremarkable and appropriate. Where an interest is sensitive – a specific armed group, a specific district before an operation, a specific abduction case – the safer pattern is to pull broadly on a routine schedule and run the narrow query against your own copy, so that the analytical question never leaves your infrastructure. Registration details are themselves disclosive: an institutional address on the account associates your organisation with conflict analysis in a way that may or may not matter to you. Downstream, be careful about republishing precise event locations in products that could reach parties to a conflict, since the combination of a coded location with your own operational context can identify sources, staff or affected communities in ways that neither dataset does alone.

Two rules that hold regardless of jurisdiction. Collection that is lawful is not automatically proportionate, and a dataset assembled for one purpose does not carry consent for another. Where the records concern identifiable people, the question is not only whether you may hold the data but whether holding it serves the purpose you are accountable for.

Is it earning its place?

Sources accumulate. Feeds get added during an incident and are never reviewed again, and a decade later the pipeline is carrying dead weight that nobody dares remove. These are the measures that show whether ACLED Conflict Events is contributing anything, and they are worth baselining now so the answer is available later.

Collection continuity: whether the weekly pull completed and returned a plausible volume for each country, since a silent failure is indistinguishable from a quiet week and both look like good news.
Backfill magnitude: how much the most recent two weeks grow in subsequent pulls, which quantifies the reporting lag for your areas of interest and tells you how long to wait before drawing a conclusion.
Revision rate: how many historical events change, merge or disappear per full refresh, which measures how far an append-only archive would have drifted.
Precision profile: the share of events at each geographic and temporal precision level for your countries, reported alongside any spatial or daily-resolution product.
Source scale mix: the distribution of local, national and international sourcing per area, which is the practical measure of reporting environment and the control variable for cross-country comparison.
Actor reconciliation coverage: the proportion of actor names successfully mapped to canonical entities including aliases and successors, which gates all longitudinal organisational analysis.
Alert precision: the share of pattern-based alerts that analysts judge meaningful, tracked to prevent volume-driven alerting from quietly re-establishing itself.
Attribution compliance: the proportion of published products carrying the required attribution and snapshot date, which is both a licence obligation and a reproducibility requirement.

Beware of volume. Indicator counts rise easily and say almost nothing. Unique contribution — findings this source produced that no other source in your stack would have — is the measure that matters, and it is usually far lower than anyone expects.

Tradecraft notes

The distinctions that separate a competent analyst from a fast one:

Event counts measure reporting. This is the first and last thing to remember about this dataset, and nearly every misuse of it is a version of forgetting it for one paragraph.
The precision fields are not metadata, they are the confidence interval. An event coded to a provincial centre is a claim about a province, and putting it on a map as a point makes a claim the data does not support.
Strategic developments are not violence. Check what your filter includes before you report a conflict trend, because the default of taking everything will fold arrests and agreements into your violence line.
Sub-event type is where the analysis lives. The shift from armed clashes to remote explosives, or from clashes to civilian targeting, describes a change in the conflict that no aggregate count will show.
The most recent week always looks quiet and never is. Build the reporting lag into your reading or you will brief a decline every time you brief.
Fatalities are the weakest field and the producer says so plainly. An analysis that depends on them needs corroboration; an analysis that does not need them should not include them.
Actor names are coding decisions about entities that deliberately obscure their own identity. Maintain your own reconciliation and treat any longitudinal group claim as resting on it.
The notes field is searchable and frequently contains what you concluded was missing. Search it before asserting that the dataset does not cover something.
For kidnap work, remember which dataset you are in. Politically motivated abduction is coded; criminal kidnap for ransom largely is not, and the difference between those two facts is the difference between a useful assessment and a badly wrong one.

Questions analysts actually ask

Can I compare violence between two countries by counting events?

Only after controlling for the reporting environment, and even then cautiously. Event counts track media and partner coverage, which varies enormously with press freedom, connectivity and language. Use the source scale fields to characterise each environment and state the limitation in the product.

Why do my numbers change when I re-run the same query?

Because historical data is under continuous review and events are corrected, merged, split and deleted. Record a snapshot date with every extract and schedule periodic full refreshes, otherwise your archive will drift from the source without any signal.

Is the API endpoint still the same?

Access arrangements have changed, including a migration away from the older email-and-key read endpoint to an account and token model. Consult ACLED's current access documentation before writing a client rather than reusing older code, and expect the terms attached to your tier to be enforced.

Can I use ACLED for kidnap-for-ransom risk analysis?

Partially. The abduction and forced disappearance sub-event type captures politically motivated abduction as reported, which is genuinely useful for environmental assessment, but ACLED is a political violence dataset and ordinary criminal kidnapping is largely out of scope. Pair it with crime statistics and case data, and never present ACLED counts as a kidnap rate.

Why are there so many events at provincial capitals?

Because events whose location is only known to the level of an administrative region are coded to a representative point, usually the administrative centre. Filter on geographic precision before mapping, or you will report a coding convention as a hotspot.

Should I use fatalities to measure conflict intensity?

Prefer event counts by sub-event type, with fatalities as a secondary and corroborated line. ACLED itself identifies fatalities as its least reliable field: figures are conservative, often unavailable, contested by parties and revised over time.

How does this differ from other conflict event datasets?

Mainly in inclusion criteria and event definition. ACLED codes a broader range of activity including protests and non-violent strategic developments, and defines events at a finer grain, so its counts are not comparable with datasets built on narrower definitions. Use another dataset to validate direction, not to check numbers.

Can I put ACLED data in a commercial product?

Not under the free terms. Commercial use requires a licence agreement with ACLED, and the boundary covers paid products and fee-earning client work. Settle this before deployment, and carry the attribution requirement through to every output either way.

What does the platform add over the raw feed?

Scheduled collection with snapshot retention and periodic full refresh, precision fields preserved through to rendering, actors reconciled to canonical entities across renaming and fragmentation, and events used as the dated spine that undated sources are anchored against. The coding remains ACLED's; nothing in the platform generates, geolocates or attributes an event.

Standards, formats and interoperability

What this source speaks natively, and what it has to be translated into before a partner can consume it. Work that arrives in a recognised format is easier to defend, easier to hand over and easier to automate against:

The ACLED codebook is the authoritative definition of event types, sub-event types, actor classifications and precision codes, and is the document any integration should be built against rather than inferred from column contents.
Administrative hierarchies follow national administrative divisions, which change over time and differ from other datasets' geographies, so joins to other spatial data need an explicit boundary vintage.
Coordinates are WGS84 decimal degrees and should carry the geographic precision code wherever they are rendered or exported, including into MGRS for defence consumers.
Country identification should be normalised to ISO 3166 on ingest, with the dataset's own ISO field checked rather than assumed for territories with contested status.
In the platform, events normalise to dated, geolocated observation records linked to actor and country entities and export as STIX 2.1, MISP, CSV, JSON, JSONL and TAXII 2.1 collections.
Humanitarian data interchange conventions, including common operational datasets for administrative boundaries and place codes, are the practical interchange standard when combining with displacement and needs data.
The dataset has no natural expression in detection formats such as YARA, Sigma or network signatures, and attempts to force it into indicator-style structures lose the precision and actor semantics that make it useful.

References

Primary documentation and authoritative references for this source. Publishers revise and retire material, so treat the retrieval date as part of the citation and re-check before relying on any of it in a formal product.

ACLED — Armed Conflict Location and Event Data Project. The organisation and the route to data access, documentation and analytical products. The correct citation target and the place to check current access terms.
ACLED methodology — ACLED. How events are defined, sourced and coded, including the sourcing hierarchy and the review process. Read before building anything on the data.
ACLED Knowledge Base — ACLED. Guides, definitions, regional methodology notes and answers to the questions analysts actually have. The most practically useful documentation the project publishes.
ACLED Codebook — ACLED. The field-by-field specification of the schema and taxonomy. Note the edition; the taxonomy has been revised and the current version should be confirmed against the knowledge base.
ACLED data access — ACLED. The current export and access routes. Consult this rather than reusing an older integration pattern, because the access model has changed.
ACLED curated data files — ACLED. Assembled regional and thematic files intended for bulk use, and the right starting point for historical baselines rather than paging an interface.
ACLED API documentation — ACLED. The programmatic interface reference. Treat this as the authority on authentication, parameters and throughput rather than any secondhand description.
ACLED Terms of Use — ACLED. The licensing boundary between free non-commercial use and commercial use, and the attribution requirement. Read it before deployment, not after.
ACLED Conflict Index — ACLED. The project's own periodic ranking of conflict severity, useful as a check on whether your automated reading of the data matches the producer's analytical judgement.
Uppsala Conflict Data Program — Uppsala University. The main independently coded alternative, with different inclusion criteria and event definitions. The standard external validity check.
GDELT Project — GDELT. Machine-extracted global media event data at high volume and low precision, useful for characterising the media environment that ACLED codes from.
ReliefWeb — UN OCHA. Humanitarian situation reporting covering the consequences of coded events and occasionally recording incidents that never reached commercial media.

Link integrity: every reference above was verified with a live request when this page was generated. Where a publisher had moved or withdrawn a document, the link was repointed at a preserved copy in the Internet Archive and marked as archived. Anything with no reachable copy anywhere had its link removed rather than left to rot — the source is still credited, it simply cannot be linked.

Put it into practice

The Quantus Intel threat intelligence platform operationalises this source: it collects the weekly release incrementally with full-history refresh and snapshot retention, preserves the temporal and geographic precision codes through to every map and export, reconciles actor names into stable entities across fragmentation and renaming, and uses the event stream as the dated spine that undated sources across the catalogue are anchored against.. Browse the full source catalogue, or follow any tag above into the rest of the library.