Deleted Endpoint

The ACLED dataset is updated weekly. Many events are added, but events can also be deleted if new information emerges that places an event outside of ACLED’s remit, or to avoid duplicate events in the dataset. If these deletions are not taken into account, your downloaded dataset will eventually look different from the latest (most up-to-date) version of the ACLED dataset. You can update your dataset by retrieving deleted event IDs (corresponding to the event_id_cnty values) from the deleted endpoint and then removing those events from your locally downloaded dataset. You can find a more general guide on keeping your dataset updated here.

In this section you will learn about the following aspects of the deleted endpoint:

Starting your call

You will need to build a unique URL to execute your API call (i.e. your data request) and download your data. Importantly, the initial part of your URL will differ when using the deleted endpoint versus other endpoints. Remember that the ACLED endpoint uses the following as the beginning of the URL: https://api.acleddata.com/acled/. When building a URL using the deleted endpoint, /acled/ is replaced with ’/deleted/, so your URL should begin with https://api.acleddata.com/deleted/. Beyond this small difference, building your URL for the deleted endpoint is identical to making a URL for any other endpoint offered by ACLED’s API.

If you are unfamiliar with how to use ACLED’s API we recommend that you begin by learning the basics of building URLs for API calls in our Get started and Advanced concepts sections.

You must first specify your preferred file format for download ("read"+{desired file format extension}) and provide your unique authentication credentials. Your URL to request all available data from the deleted endpoint would then look something like this:

https://api.acleddata.com/deleted/read.csv?key=your_key&email=your_email

Remember: As covered in the Get started section, your key and email address must be included in all requests. If you do not already have a key you can register here.

Query filters

Instead of receiving all the data from the deleted endpoint, you can select a subset of data by applying query filters (see Advanced concepts). You can specify which data your API call should return by using the following filters:

Table 1: Query filters for the deleted endpoint
Query Name Type Query String
key = ?key={api_key}
email = ?email={email address associated with key}
event_id_cnty LIKE ?event_id_cnty={text}
deleted_timestamp >= ?deleted_timestamp={unix timestamp or yyyy-mm-dd}

Like filters for other endpoints, these query filters are assigned a default query type (either =, >=, or LIKE). If you would like to do so, you can change a filter’s type by adding _where= at the end of the query name, followed by the desired type. For a detailed explanation of query types, visit the Advanced concepts section.

Note: If you want to change the query type for the deleted_timestamp query filter, you must use a Unix timestamp instead of a date. You can convert a date to a Unix timestamp using any online timestamp calculator, such as the one linked here.

Returned data

The deleted endpoint returns a dataset with only two columns: event_id_cnty and deleted_timestamp.

Table 2: Returned data from deleted endpoint
Attribute Name Type Description
event_id_cnty string An individual identifier by number and country acronym
deleted_timestamp int/date The unix timestamp when this data entry was deleted

You can learn how to use these data to update your own downloaded dataset in this guide.

Returned data - JSON only.

If you request data in a JSON format, the deleted endpoint will return additional information:

Table 3: Returned data from deleted endpoint if requested in JSON form.
Attribute Name Type Description
status int A number representing the request status
success boolean A boolean representation on the success of the call
last_update int The number of hours since the last update to the data
count int The number of data rows returned
messages array An array of information messages that may require future action
data array The rows of data returned. For details of attributes returned in each row, see the section above
filename string The filename that will be used for .csv calls
error array The details of the error with a status as an integer and message as a string

Example - URL 💻

The following example demonstrates how to build an API call for the deleted endpoint. Imagine you want to gather all events that were deleted between November 2022 and March 2023. Note that these are events that were deleted during this time period, not deleted events with event_date values between November 2022 and March 2023.

  1. Begin with the ACLED API’s base URL.

https://api.acleddata.com/

  1. Add the deleted endpoint.

https://api.acleddata.com/deleted/

  1. Specify the response format.

https://api.acleddata.com/deleted/read.csv

  1. Include your credentials.

https://api.acleddata.com/deleted/read.csv?key=your_key&email=your_email

  1. Add query filters specifying the timestamp parameters.

https://api.acleddata.com/deleted/read.csv?key=your_key&email=your_email&deleted_timestamp=1667319467|1677641513

  1. Add an extra parameter with the suffix _where to specify that you want deleted timestamps between the selected values.

https://api.acleddata.com/deleted/read.csv?key=your_key&email=your_email&deleted_timestamp=1667319467|1677641513&deleted_timestamp_where=BETWEEN

Now you can paste the URL into your internet browser, execute your API call, and receive your data.

Example - Python

You can perform the same request using Python. Remember that you are trying to find:

  • All deleted events,

  • From November 2022 to March 2023.

You should start by importing the necessary modules: requests and json.

import requests
import json

As discussed in the ACLED endpoint section, the requests module provides you with two options when performing an API call:

  1. Use your full URL as the first argument in requests.get().

  2. Alternatively, remove the query filters from your URL and pass them as a dictionary to the params argument of requests.get().

You can follow along with both methods below.

For option #1, you can use the URL you created above:

https://api.acleddata.com/deleted/read.csv?key=your_key&email=your_email&deleted_timestamp=1667319467|1677641513&deleted_timestamp_where=BETWEEN

# Option 1
# Request the data as a JSON file 
response_deleted_full_url = requests.get("https://api.acleddata.com/deleted/read?key=your_key&email=your_mail&deleted_timestamp=1667319467|1677641513&deleted_timestamp_where=BETWEEN")
if response_deleted_full_url.json()['status'] == 200:
  print("Congratulations! Request successful! Take a peek to the returned JSON structure.")
Congratulations! Request successful! Take a peek to the returned JSON structure.

In the second option, you should instead use the base URL with the endpoint and read + {file extension} command as the URL argument while passing the query filters as a dictionary to the params argument.

# Option 2
# We create a dictionary of parameters.
parameters = {
  "email": "your_email",
  "key": "your_key",
  "deleted_timestamp" : "1667319467|1677641513",
  "deleted_timestamp_where" : "BETWEEN"
}
# We request the data as a JSON file and pass our paramenters as an argument (params=)
response_deleted_params_dic = requests.get("https://api.acleddata.com/deleted/read", params= parameters)
if response_deleted_params_dic.json()['status'] == 200:
  print("Congratulations! Request successful! Take a peek to the returned JSON structure.")
Congratulations! Request successful! Take a peek to the returned JSON structure.

Both options achieve the same result. Which option is best for you will depend on your knowledge of API requests and your intended use of the data.

Best of luck! 🚀

Example - R

Working with ACLED’s API in R is straightforward.

You can start by loading the packages you are going to need:

library(httr)  # For handling API requests
library(jsonlite) # For handling the response of the API
library(dplyr) # For handling data

Remember that you are trying to find:

  • All deleted events,

  • From November 2022 to March 2023.

Like the Python example, there are two approaches you can use when executing your API call. You can either pass the full URL with query filters to the httr::GET() function, or you can pass in the API’s base URL with the read command and use a named list of parameters to specify query filters.

# Option 1
# We execute our call
response <- GET("https://api.acleddata.com/deleted/read?key=your_key&email=your_emal&deleted_timestamp=1667319467|1677641513&deleted_timestamp_where=BETWEEN") 
# We transform the API response into a dataframe
response_json <- jsonlite::fromJSON(content(response, "text"), simplifyVector=T)
response_df_option1 <- as.data.frame(response_json$data)
# Option 2
# We set up the list of parameters
parameters <-  list(
  email= "your_email",
  key= "your_key",
  deleted_timestamp = "1667319467|1677641513",
  deleted_timestamp_where = "BETWEEN",
  
)
# We execute our call
response <- GET("https://api.acleddata.com/deleted/read", query = parameters)
# We transform the API response into a dataframe
response_json <- jsonlite::fromJSON(content(response, "text"), simplifyVector=T)
response_df_option2 <- as.data.frame(response_json$data)

Both options are valid, as they produce the same results. The option that is optimal for you will depend upon your specific use case.

Best of luck! 🚀