ACLED maintains a living dataset. This means that in addition to weekly updates to the data from the week prior, there may be other additions, substitutions, and deletions. These can include updates to events already in the dataset — such as updated fatality counts as death tolls mount, or the name of a group that claims responsibility for an attack, or a more precise location if new information comes to light. In such cases, the EVENT_ID_CNTY remains the same, but the relevant aspects of the event coding are updated and ‘overwritten.’
In addition to these updates, weekly data can occasionally include new supplemental data. These events are the result of targeted data reviews, the identification of new sources, a new partnership with a local conflict observatory, or the enrichment of previous coverage with information coming in from established partnerships. All may result in the addition of new historical events to the dataset.
Lastly, events are occasionally removed from the ACLED dataset if new information comes to light to disqualify it from inclusion or if the event is merged with another event. The latter is done to avoid duplicate events. Per ACLED methodology, violent events involving the same actors occurring on the same day in the same location are aggregated into a single event; the same is done for demonstrations occurring on the same day in the same location over the same issues (for more, see the ACLED Codebook).
Because of these varied additions and updates to weekly data, if a user only downloads events that occurred during the prior specific week, these updates and other additions will be missed. Furthermore, if a user does not take into account deleted events, the user’s personal ACLED data file will eventually look different from the latest (most up-to-date) version of the ACLED dataset.
To avoid this, you must update your personal ACLED data file. To do this:1An alternative option is to download the full, latest version of the dataset each time it is required for analysis to ensure the most up-to-date information is included. This is notsuggested as regular downloading of the entire one million+ event ACLED dataset — including events that are unchanged — is redundant and inefficient. Using the targeted method of updating select events is a much faster and more efficient way of keeping your ACLED dataset up to date
- Remove any deleted EVENT_ID_CNTY by checking for deleted events weekly and removing them from your personal ACLED data file;
- Replace old events (via their EVENT_ID_CNTY) which have been updated and append new events that were recently published. This can be done by calculating the relevant timestamp (more on that below).
Noted below are the steps to calculate the relevant timestamp to download new, updated, and deleted ACLED events.
Calculate the relevant timestamp
To filter data on time of upload, users must use the ‘timestamp’ field. This is an automatically generated value that represents the exact date and time an event was uploaded to the ACLED API. It is formatted as a Unix timestamp, corresponding to the number of seconds passed since 1 January 1970.
It is necessary to first determine the Unix timestamp corresponding to the ‘start date’ (the earliest upload/deletion date in which the user is interested). You may choose, for example, to select the day after your last data download; this would ensure that you catch any and all new updates since that time. To determine the Unix timestamp corresponding to the ‘start date’ you are interested in, you can use an online Unix timestamp converter,2
This can also be calculated in Excel:
Example: To filter data uploaded after 17 June 2019, enter “17/06/2019”.
=(A1-DATE(1970,1,1))*86400
3. The resulting number in cell A2 will be the Unix timestamp for 17 June 2019, 12:00:00 AM (UTC). In this example, that equals “1560729600”.
or you can calculate this in Excel by doing the following:
Download ACLED data based on upload date:
Use this generated Unix timestamp to filter events that were uploaded (whether as a new event or an update to an already existing event) after your ‘start date’ of interest. This can be done using an Excel download of the data or by pulling from the API directly.
(1) If working with a downloaded Excel or CSV file of ACLED data:
The screenshots below show how to search for events uploaded or updated on or after 17 June
2019 at 12:00:00 AM (UTC). The start date timestamp associated with this date and time is 1560729600.
1. Select all (Ctrl+A or Cmd+A), go to the ‘Data’ tab in Excel, and select ‘Sort.’ In the dialogue box, choose ‘timestamp’ from the Column drop-down menu and select ‘Largest to Smallest’ in the order drop-down menu. (Be sure to select the “My list has headers” option.) By sorting the timestamp column from largest to smallest, the most recent events will be at the top of the column.
2. Since Unix timestamps represent the date and exact time of upload (down to seconds), it is unlikely that an exact match of the start date will exist in the ‘timestamp’ column (this would assume the last data upload occurred at precisely 12:00:00 AM (UTC) on 17 June 2019). To find all of the events uploaded on or after the specific timestamp of interest (here, for example, on or after 17 June 2019 at 12:00 AM (UTC)), scroll through the ‘timestamp’ column until the numbers become smaller than the start date timestamp, which in our case here would be 1560729600 (as seen in the screenshot below). Any events located above that cell have larger timestamp numbers, indicating that they were uploaded after the ‘start date’ of interest; in other words, these are the new and updated events.
(2) If pulling directly from the API:
- Consult the ACLED API User Guide for how to build an API query.
- At the end of the query, add the search terms for the TIMESTAMP field:
?timestamp={number/yyyy-mm-dd}
Note: It is not necessary to use a “>” sign to search for events with timestamps greater than the start date. The “=” in the query will return timestamps greater than or equal to the timestamp indicated.
Example query ending for events uploaded on or after 17 June 2019 at 12:00:00 AM (UTC):
?timestamp=1560729600/2019-06-17
Look up deleted events
To determine which events have been deleted, users can query the Deletions API. The API query returns the EVENT_ID_CNTY value of events that were deleted recently, as well as the timestamp of when they were removed from the ACLED dataset. Note that the Deletions API only contains events that were deleted on or after 9 July 2021. For a complete list of deleted event IDs, including ones that were deleted prior to 9 July 2021, download the Deleted Events file.
Similar to the ‘timestamp’ field in the ACLED dataset, the ‘DELETED_TIMESTAMP’ field in the Deletions dataset is formatted as a Unix timestamp. To find events that were deleted after a certain point in time, calculate the Unix timestamp for that date and time and then query for (or filter for) entries with a timestamp greater than that number.
(1) If pulling directly from the API:
- Consult the ACLED API User Guide for how to build an API query.
- At the end of the query, add the search terms for the DELETED_TIMESTAMP field:
?deleted_timestamp={number/yyyy-mm-dd}
Note: It is not necessary to use a “>” sign to search for events with timestamps greater than the start date. The “=” in the query will return timestamps greater than or equal to the timestamp indicated.
Example query ending for events deleted on or after 19 July 2021 at 12:00:00 AM (UTC):
?deleted_timestamp=1626667200/2021-07-19
(2) If working with the Deleted Events file:
The screenshots below show how to search for events deleted on or after 19 July 2021 at 12:00:00 AM (UTC). As noted above, the start date timestamp associated with this date and time is 1626667200.
- Select all (Ctrl+A or Cmd+A), go to the ‘Data’ tab, and select ‘Sort.’ In the dialogue box, choose ‘DELETED_TIMESTAMP’ from the ‘Column’ drop-down menu and select ‘Largest to Smallest’ in the ‘Order’ drop-down menu. By sorting the deleted timestamp column from largest to smallest, the most recent deleted events will be at the top of the column.
- Since Unix timestamps represent the date and exact time of deletion (down to seconds),
it is unlikely that an exact match of the start date will exist in the ‘deleted_timestamp’ column (this would assume the last data deletion occurred at precisely 12:00:00 AM (UTC) on 12 July 2021). To find all of the events deleted on or after the specific ‘start date’ of interest (here, for example, on or after 12 July 2021 at 12:00 AM (UTC)), scroll through the ‘deleted_timestamp’ column until the numbers become smaller than the start date timestamp (as seen in the screenshot below). Any events located above that cell have larger timestamp numbers, indicating that they were deleted after the timestamp of interest; in other words, these are the recently deleted events.
Note: Events that were deleted before 9 July 2021 will not have a timestamp value. These event IDs will have a blank value in the ‘deleted_timestamp’ field.
