Accessing the API
To use ACLED’s API, you must first register an account in ACLED’s Access Portal. You can find more information about registering your account by visiting ACLED’s access guide.
There are three ways to authenticate your credentials, outlined here from most to least recommended:
Use acled_access() (recommended)
acled_access() both verifies your credentials and stores
them in your local environment for a given session. After running the
following code, you can make API requests without manually entering your
credentials within each call.
acled_access("your_email", "your_key") # to be run every session before doing an API call. Store credentials as environmental variables
You can alternatively store your credentials for permanent use across all sessions. To do so, run the following:
which will open your .Renviron file. Once open, set:
email_address = "your_email"
acled_key = "your_key"Afterwards, save the file and restart your R session. You can confirm
that they have been properly stored by running
Sys.getenv("email_address") to return the stored email
address and Sys.getenv("acled_key") to return the stored
ACLED key in the console. You can then enter your credentials within
each API call like:
acled_api(
email = Sys.getenv("email_address"),
key = Sys.getenv("acled_key"),
acled_access = FALSE,
...)Manually enter credentials within each call (not recommended)
As a final option, you can manually enter your credentials within each API call. While we do not recommend this approach because it is the least secure, it may be suitable for some use cases. You can use this option by following this example:
acled_api(
email = "email_address",
key = "acled_key",
acled_access = FALSE,
...)ACLED API
acled_api() is a function you can use to request and
process ACLED API calls. The function takes the following arguments:
Parameters for the API
Geographical filters
You can use the country and regions
parameters to specify the locations from which you would like to request
data. If both values are NULL or are not included, the API
will return data for all countries and regions. If you would like to
request data for multiple countries, you can do so by using a vector of
country names (e.g., c("Argentina","Spain","Bolivia")).
Similarly, you can request data from one or more regions by using either
a vector of region names or numeric codes.
acledR::acled_countries and
acledR::acled_regions show the full lists of countries and
regions available. Please visit ACLED’s Knowledge
Base for region-specific methodology questions.
Temporal filters
You can specify the date range for which you would like to receive
data by using the start_date and end_date
parameters, both of which require data in the “yyyy-mm-dd” format.
You can use the timestamp parameter to select data that
were added or updated over a specific time period. Please keep in mind
that timestamp indicates when the event was added or
modified in ACLED’s dataset, meaning that an event that occurred far in
the past (i.e., with an old event date) may still have a recent
timestamp if it was recently updated.
In practice, the timestamp parameter is typically not
used for analysis but is instead used to keep your own dataset up to
date as changes are made to ACLED’s data. To learn more about how to
keep your datasets up to date, visit the Keeping
your datasets up to date page for an acledR approach or this guide more relevant to
Excel or other spreadsheet tools.
Additional filters
You can also use the event_types argument to filter to
specific event_types in ACLED data. To do so, you should enter
the event_type of interest as a string or as a vector of
strings (e.g., event_types = "Battles" or
event_types = c("Battles", "Protests")). For a description
of all available event_types in ACLED’s dataset, please refer
to ACLED’s
codebook.
ACLED data defaults to a wide (or dyadic) format, where each row
contains multiple actor columns, with those actors interacting during
the event. However, you can request a long (or monadic) format using the
monadic argument. By default, this argument is
FALSE, meaning you will receive a dyadic version of the
data. When monadic=TRUE, the function will return a monadic
(“long-form”) data frame with only one actor (based on actor1
and actor2). For transforming your dataset from wide to long
without using the API, or transforming it based on different sets of
columns, visit acled_transform_longer(). For more
information on the difference between our wide/dyadic and monadic/long
datasets, please visit our API
guide
Finally, you can use the population argument to specify
if you want to include the estimated population exposure columns. This
argument takes three options, none which returns no extra
columns, best which only returns the population_best
column, or full which returns all the estimated population
columns. For more information, visit our Conflict Exposure
piece.
The ... parameter represents any other arguments you
might want to include in your API query, such as ISO or
Interaction. If you want to use these filters or others not
included in the list of parameters described above, then you can write
them as ¶menter=value. For instance, you might wish
to include &iso=4 at the end of the function. You can
visit ACLED’s API guide
to learn more about other valid parameters.
Function options
You can use the prompt argument to specify how the
function handles API calls that return large amounts of data. If
prompt=TRUE, then you will receive an interactive prompt
(see Handling big API calls immediately below). If you do
not want this interactive prompt (e.g., because acled_api()
is part of a routine script), then you can set
prompt = FALSE.
Handling big API calls
As is common when executing API calls, handling large volumes of data
requires some special consideration. In ACLED’s case, the base API uses
pagination to address some of these issues, but pagination can be
confusing for newer users (see our API
guide for a more detailed explanation). Fortunately, this package
avoids this issue. Instead of manual pagination, the
acled_api() function splits the call automatically.
acled_api() will first estimate how much data you are
requesting. You will then be prompted with a message which includes the
following:
The number of countries for which data is being requested,
The number of estimated events requested (based only on country and year, and NOT event type),
The number of API calls needed, based on an estimate of how big the call is,
A question asking whether given this information and the number of available API calls linked to your account – you would like to proceed with your API call.
Example - Requesting data with acled_api()
Imagine you are interested in events from Argentina occurring between June 1-30 2022
library(acledR)
library(dplyr)
#Note: This is simply an example–you will need to include your own credentials rather than the email and key placeholders that are included below.
acled_access(email = "your_email", key = "your_key")
df_ar <- acled_api(country = c("Argentina"),
start_date = "2022-06-01",
end_date = "2022-06-31",
monadic = F,
acled_access = TRUE,
prompt = F)This returns a tibble that includes each ACLED event in Argentina during the specified period:
head(df_ar, 5)
#> # A tibble: 5 × 31
#> event_id_cnty event_date year time_precision disorder_type event_type
#> <chr> <date> <dbl> <dbl> <chr> <chr>
#> 1 ARG10607 2022-06-30 2022 1 Demostrations Protests
#> 2 ARG10626 2022-06-30 2022 1 Demostrations Protests
#> 3 ARG10618 2022-06-30 2022 1 Demostrations Protests
#> 4 ARG10615 2022-06-30 2022 1 Demostrations Protests
#> 5 ARG10627 2022-06-30 2022 1 Demostrations Protests
#> # ℹ 25 more variables: sub_event_type <chr>, actor1 <chr>, assoc_actor_1 <chr>,
#> # inter1 <dbl>, actor2 <chr>, assoc_actor_2 <chr>, inter2 <dbl>,
#> # interaction <dbl>, civilian_targeting <chr>, iso <dbl>, region <chr>,
#> # country <chr>, admin1 <chr>, admin2 <chr>, admin3 <lgl>, location <chr>,
#> # latitude <dbl>, longitude <dbl>, geo_precision <dbl>, source <chr>,
#> # source_scale <chr>, notes <chr>, fatalities <dbl>, tags <chr>,
#> # timestamp <dbl>If you wanted data from both Brazil and Colombia, you would execute the following:
df_br_co <- acled_api(country = c("Brazil", "Colombia"),
start_date = "2022-01-01",
end_date = "2022-12-01",
monadic = F,
acled_access = TRUE,
prompt = F)If you are interested in events occurring over a larger area, it may
be simpler to omit the country parameter and include a
regions argument instead. You could also include an
event_type argument to receive only a specific type of
event:
df_sa <- acled_api(regions = c("South America"),
start_date = "2022-01-01",
end_date = "2022-12-01",
event_type = "Protests",
monadic = F,
acled_access = TRUE,
prompt = F)You can use the timestamp column/filter to specify the dates from which you would like to receive new or updated data. You can include the argument as either a string (“yyyy-mm-dd”) or a numeric Unix timestamp:
df_br_co <- acled_api(country = c("Brazil", "Colombia"),
start_date = "2022-01-01",
end_date = "2022-12-01",
monadic = F,
# timestamp = "2022-01-24" -> in the case of string
timestamp = 1643056974, # -> in the case of a numeric Unix timestamp
acled_access = TRUE,
prompt = F)If you would like to include only one type of interaction
(e.g., “Rioters versus Civilians (57)”), then you can add
interaction code to the ... argument:
df_sa <- acled_api(country = c("Brazil", "Colombia"),
start_date = "2022-01-01",
end_date = "2022-12-01",
monadic = F,
... = "&interaction=57",
acled_access = TRUE,
prompt = F)You could also request the monadic version of the data by setting
monadic = TRUE: