| acled.api {acled.api} | R Documentation |
Automated Retrieval of ACLED Conflict Event Data
Description
Access and manage the application programming interface (API)
of the Armed Conflict Location & Event Data Project (ACLED).
The function acled.api() makes it easy to retrieve a user-defined sample (or all of the
available data) of ACLED, enabling a seamless integration of regular data updates into
the research work flow. If the data are intended for replicable use (e.g., later publication of analysis results), the
downloaded data should be stored locally after retrieval. See the package's README file for a
note on replicability when using ACLED data.
When using this package, you acknowledge that you have read ACLED's terms and
conditions of use, and that you agree with their attribution requirements.
Usage
acled.api(
email.address = Sys.getenv("ACLED_EMAIL_ADDRESS"),
access.key = Sys.getenv("ACLED_ACCESS_KEY"),
country = NULL,
region = NULL,
start.date = NULL,
end.date = NULL,
add.variables = NULL,
all.variables = FALSE,
dyadic = FALSE,
interaction = NULL,
other.query = NULL
)
Arguments
email.address |
character string. Supply the email address that you registered with ACLED access.
The email address can also be set as an environment variable using |
access.key |
character string. Supply your ACLED access key. The access key can also be set as an environment variable
using |
country |
character vector. Supply one or more country names to narrow down which events should be retrieved. See the details below for information on how the arguments "country" and "region" interact. |
region |
numeric or character vector. Supply one or more region codes (numeric) or region names (character)
to narrow down which events should be retrieved. You can run |
start.date |
character string. Supply the earliest date to be retrieved. Format: "yyyy-mm-dd". |
end.date |
character string. Supply the last date to be retrieved. Format: "yyyy-mm-dd". |
add.variables |
character vector. Supply the names of ACLED variables you wish to add to the default output (see ACLED's codebook for details). The default output includes: event_id_cnty, region, country, year, event_date, source, admin1, admin2, admin3, location, latitude, longitude, event_type, sub_event_type, interaction, fatalities, tags, and the download timestamp. |
all.variables |
logical. When set to FALSE (default), a narrow default selection of variables is returned (which can be refined using the argument add.variables). If set to TRUE, all variables are included in the output (overrides argument add.variables). |
dyadic |
logical. When set to FALSE (default), monadic data is returned (one observation per event). If set to TRUE, dyadic data is returned. |
interaction |
numeric vector. Supply one or more interaction codes to narrow down which events should be retrieved (see ACLED's codebook for details. |
other.query |
character vector. Allows users to add their own ACLED API queries to the GET call. Vector elements are assumed to be individual queries, and are automatically separated by an & sign. See ACLED's API Guide for information on making your custom query. |
Details
The function acled.api() is an R wrapper for
the Armed Conflict Location & Event Data Project API.
Internally it uses httr to access the API, and jsonlite to manage the JSON content that the call returns. The JSON data
are converted into the base class data.frame. Variables are of class character by default.
Variables which only contain numbers as recognized by the regular
expression ^[0-9]+$ are coerced into numeric before the data.frame object is returned.
Authentification: The user's registered email address and ACLED access key, which they obtain after registering with ACLED access, can be supplied as strings directly to their respective arguments,
or set in advance as environment variables
using
Sys.setenv(ACLED_EMAIL_ADDRESS="your.email.address") and
Sys.setenv(ACLED_ACCESS_KEY="your.access.key").
Retrieving all data at once: If both the country argument and the region argument are NULL (default), all available countries are retrieved. The same applies to
the time frame when both the start date and the end date are NULL (default). Note that the API cannot handle requests with only one
of the dates specified (either none of them or both of them need to be supplied). More recent versions of the API implemented a bandwidth limit that prevents
users from retrieving larger amounts of data in a single call. At the time of this writing (v. acled.api() 1.1.8), ACLED recommends using pagination to retrieve data
in separate calls of 5000 rows each. This is much less than what is actually possible to retrieve in a single call, and with a full dataset of >2 million rows, pagination is less
practicable than simply downloading by individual regions or time periods. The separate data chunks obtained this way can then be combined using rbind(). Users who want to make use of
pagination can do so using the other.query filter.
Filter combinations: By default, acled.api() combines different filters with a logical AND operator.
This usually conforms with desired behavior, with the country argument and the region argument as important exception: for example, specifying the
country "Togo" and the region "Southern Africa" leads the API to query for a country named "Togo" in the region "Southern Africa".
In this case, no data will be returned as no events match this query, and it is recommended to make two separate calls, one for Togo and one for Southern Africa.
More recent versions of the API also support OR operators to separate filters. These can be implemented through acled.api() by using the other.query filter.
To do so, see the ACLED API Guide for details.
Value
A data frame containing ACLED events.
Author(s)
Christoph Dworschak
Website: https://www.chrisdworschak.com/
References
Armed Conflict Location & Event Data Project (ACLED); https://acleddata.com/
Clionadh Raleigh, Andrew Linke, Havard Hegre and Joakim Karlsen. 2010.
"Introducing ACLED-Armed Conflict Location and Event Data." Journal of Peace Research 47 (5): 651-660.
Examples
## Not run:
# Email and access key provided as strings:
my.data.frame1 <- acled.api(
email.address = "your.email.address",
access.key = "your.access.key",
region = c(1,7),
start.date = "2018-11-01",
end.date = "2018-11-31")
head(my.data.frame1)
# Email and access key provided as environment variables:
my.data.frame2 <- acled.api(
email.address = Sys.getenv("ACLED_EMAIL_ADDRESS"),
access.key = Sys.getenv("ACLED_ACCESS_KEY"),
region = c(1,7),
start.date = "2020-01-01",
end.date = "2020-11-31",
interaction = c(10:18, 22:28),
add.variables = c("geo_precision", "time_precision"))
sd(my.data.frame2$geo_precision)
## End(Not run)