ACLED endpoint

In this section, you will learn how to request ACLED data using API calls to the ACLED endpoint. Here you can learn in more detail about the specific elements that form an API call to the ACLED endpoint, which returns data from ACLED’s event dataset. (To learn more about ACLED data and methodology, please see the ACLED codebook.) If you have not already done so, please see the Get started section for an explanation of how to build a basic API call. You can also learn about more techniques for using any of our endpoints in our Elements of ACLED's API guide.

This section, like the other endpoint sections, is organized as follows:

• Query filters (i.e. how to request specific data)
• Returned data
• An example call and its results

Query filters

In most cases, it is not necessary to download the entirety of the ACLED dataset, but rather a subset of the data. To avoid requesting unnecessary data, you can use “query filters” to specify the exact data you would like to receive. For instance, you can apply a query filter to your API call so that it only returns events occurring in a specific country or involving a particular actor.

All available query filters are listed in the table below. The first column contains the name of each filter, the second states the filter’s type, and the third indicates the string you must add to the API call in order to apply that filter.

Table 1: Query filters for the ACLED endpoint

Note: The string column shows the strings you should add to your URL if the filter is the first filter you use. If that particular filter is not the first you use, you should remove the ? and replace it with &.

To use these filters, add the relevant string(s) from the above table into your request. Be sure to remove the curly brackets (i.e. {}) from your URL and replace ? with & where necessary. After adding the correct query filter to your URL, you can fill in the bracketed section with the desired filter values.

For instance, to request all the data from “Canada” in 2022, you would replace {text} in the country filter with Canada and {yyyy} in the year filter with 2022. Note that you should not include brackets when entering these strings, so your request should end with the following text:

…&country=Canada&year=2022

You can also change the query type of each query filter to fit your needs. For example, to request all events during and after 2018, you cannot simply include &year=2018, since the year query filter is of type =, meaning this API call will only return events that occurred in 2018. Instead, you can change the query type to > by adding a new command with the query filter and the suffix _where, followed by the desired query type (i.e. &year=2017&year_where=>). For a more in-depth treatment of how to change query filters and what options are available, please see the Elements guide.

In the case of the population parameter, this takes two different options, either TRUE which returns only the population_best population estimate column, or full which returns all the estimates of population. For more information on the population columns, visit our Conflict Exposure piece.

On 26 September 2024, the default value of interaction code columns changed from numeric to text-based. Prior to this change, the inter1, inter2, and interaction columns appeared as numeric values that corresponded to a specific actor type in the codebook. After the change, the values appeared in the data as text. For instance, if actor1 was a ‘State forces’ actor, then before the change, the value in the inter1 column would have been ‘1’, whereas after the change, the value became ‘State forces.’

The interaction column, which was a combination of the inter1 and inter2 columns, also changed to a text-based output by default. For instance, before the change, if inter1 was 1 and inter2 was 2, the interaction column would have had the value ‘12’. After the change, the interaction column showed the text combination of the inter1 and inter2 columns (e.g., interaction = State forces - Rebel group).

Although the default output for these columns changed, we recognized that some users would want to continue receiving numeric values. As a result, a new filter was added to the API: inter_num. By setting inter_num=1, users can receive the inter1, inter2, and interaction columns with numeric values. Excluding the parameter or setting inter_num=0 returns the default text descriptors.

Note: You can convert a date to a Unix timestamp using any online timestamp calculator, such as the one linked here.

Filtering by region and actor type

There are some key differences between ACLED’s API filters and the contents of the data, particularly with respect to region names and inter codes.

Regions

region names appear in the dataset as strings (e.g. “Central America”, “Northern Africa”, etc.), but in the API, they are represented by numeric codes. For instance, if you want all the data from Western Africa, rather than including region=Western Africa in your request, you should instead include region=1. In the table below (Table 2) we outline which number you should use to request data from each region.

Table 2: Numeric codes for each region in ACLED data

Inter codes and interactions

inter1, inter2, and interaction values appear in the data as strings (e.g. “State Forces”), but in the API they are represented by numeric codes. For example, if you want to receive data for events where actor1 is “State Forces”, you should specify inter1=1 rather than inter1=State Forces. Below you can find a table (Table 3) of numeric codes corresponding to the actor types represented by inter codes. If you wish to specify events based on the interaction column, please see Table 3 of the ACLED codebook for numeric interaction values corresponding to their text-based actor types. Also note that you can receive numeric rather than text-based inter and interaction values using the inter_num filter (Table 1).

Table 3: Numeric codes for each inter type in ACLED data

Dyadic versus monadic formats - 'export_type'

ACLED data are available in two formats: dyadic (default) and monadic, specified by the export_type filter, outlined at the end of Table 1.

“Dyadic” is the default format for ACLED data. Dyadic data have a column structure that matches the structure outlined in the ACLED Codebook. This data format includes one event per row and highlights the interaction between actors. In dyadic data, actor1 and actor2 are separate columns.

However, you may wish to analyze events by making actor-based calculations rather than analyzing the interactions occurring during each event. The “monadic” data format is actor-based, with each row representing a single actor-event. Having one actor per row means that the same event may appear twice: once for each actor involved in that event (here “actor” only refers to the actors in the actor1 and actor2 columns, not the associate actor columns). Ultimately, monadic data have fewer columns because they do not include actor2, assoc_actor_2, or inter2 columns, but more rows because many events appear twice in the monadic dataset.

Table 4: Dyadic table of events

Table 5: Monadic table of events

By default, the API will return a dyadic dataset. If you would like to be returned a monadic dataset, you should add &export_type=monadic to your request.

Returned data

The data you receive from the API will include the columns listed in the table below. The table contains the name of each column, its data type, and a short description of the data in that column. For more on these columns, see the ACLED Codebook.

Table 6: Returned data’s column structure

Returned data - JSON only

As outlined in the Get started section, you can request data in different formats (i.e., .csv,.json,.xml, and .txt). If you request data in JSON format, you will receive some additional fields that are described below:

Table 7: The JSON response data

Example - URL 💻

Imagine you are interested in the types of events and the number of fatalities that occurred in the Southern Caucasus in 2021. You will likely want to gather all the events that occurred in “Georgia”, “Armenia”, and “Azerbaijan” in 2021, but for your analysis you really only need the event_id_cnty, event_date, event_type, country, and fatalities columns.

You can follow these steps to build your data request.

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

https://acleddata.com/api/

2. Add the ACLED endpoint.

https://acleddata.com/api/acled/

3. Add the response format.

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

4. Add query filters specifying the countries for which you would like to receive data.

https://acleddata.com/api/acled/read?_format=csv&country=Georgia|Armenia|Azerbaijan

5. Add a query filter to specify the year in which the events occurred.

https://acleddata.com/api/acled/read?_format=csv&country=Georgia|Armenia|Azerbaijan&year=2021

6. Next, specify which data columns you want to receive.

https://acleddata.com/api/acled/read?_format=csv&country=Georgia|Armenia|Azerbaijan&year=2021&fields=event_id_cnty|event_date|event_type|country|fatalities

Now that your query is built, you can paste it into your browser and download your data. For more instruction on building your URL please see: Elements of ACLED's API.

Examples: Python

#######################
### PYTHON EXAMPLES ###
#######################

import requests
import json

# Function to get access token using username and password
def get_access_token(username, password, token_url):
    headers = {
        'Content-Type': 'application/x-www-form-urlencoded',
    }
    data = {
          'username': username,
          'password': password,
          'grant_type': "password",
          'client_id': "acled"
    }

    response = requests.post(token_url, headers=headers, data=data)

    if response.status_code == 200:
        token_data = response.json()
        return token_data['access_token']
    else:
        raise Exception(f"Failed to get access token: {response.status_code} {response.text}")


# Get an access token
my_token = get_access_token(
    username="[email protected]",
    password="your_password",
    token_url="https://acleddata.com/oauth/token",
)


# Option #1 (parameters in the url)
base_url = "https://acledata.com/api/acled/read?_format=json&country=Georgia:OR:country=Armenia&year=2021&fields=event_id_cnty|event_date|event_type|country|fatalities"

# request base url with my_token
response = requests.get(
    base_url,
    headers={"Authorization": f"Bearer {my_token}", "Content-Type": "application/json"},
)

if response.json()["status"] == 200:
    print(
        "Request successful"
    )


# Option #2 (parameters as a dictionary)
parameters = {
    "country": "Georgia:OR:country=Armenia:OR:country=Azerbaijan",
    "year": 2021,
    "fields": "event_id_cnty|event_date|event_type|country|fatalities",
}

response_params_dic = requests.get(
    "https://acleddata.com/api/acled/read?_format=json",
    params=parameters,
    headers={"Authorization": f"Bearer {my_token}", "Content-Type": "application/json"},
)
if response_params_dic.json()["status"] == 200:
    print(
        "Request successful"
    )

Examples: R

##################
### R EXAMPLES ###
##################

library(httr2) # For handling API authorization and requests
library(jsonlite) # For handling the response of the API
library(dplyr) # For handling data

# Option #1 (parameters in the url)

# API url
api_url <- "https://acled-production.sbx.so/api/acled/read?_format=json&country=Georgia:OR:country=Armenia&year=2021&fields=event_id_cnty|event_date|event_type|country|fatalities"
# Token authorization url
token_url <- "https://acleddata.com/oauth/token"

response <- 
  # Prepare request for data from the API endpoint with parameters in the url
  request(api_url) %>% 
  # Authorize credentials
  # Can add a `password` directly (not shown); if not, a password box will pop up
  # The token will be automatically stored so you do not have to reenter your password until the token expires
  req_oauth_password(.,
                     client = oauth_client("acled", token_url),
                     username = "[email protected]"
  ) %>%
  # Execute the API request
  req_perform()

response_df_option1 <- resp_body_json(response, simplifyVector = TRUE)$data


# Option #2 (parameters as a list)

# Set up the list of parameters
parameters <- list(
  country = "Georgia:OR:country=Armenia",
  year = 2021,
  fields = "event_id_cnty|event_date|event_type|country|fatalities"
  )

response <- 
  # Prepare request for data from the API endpoint. Note that only the base url is provided this time
  request("https://acleddata.com/oauth/token/api/acled/read?_format=json") %>% 
  # Authorize credentials
  req_oauth_password(.,
                     client = oauth_client("acled", token_url),
                     username = "[email protected]"
  ) %>%
  # Add list of parameters
  req_url_query(!!!parameters) %>% 
  # Execute the API request
  req_perform()

response_df_option2 <- resp_body_json(response, simplifyVector = TRUE)$data