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("EMAIL_ADDRESS"),
  access.key = Sys.getenv("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 Sys.setenv(EMAIL_ADDRESS="your.email.address"), in which case this argument can be skipped. Usage examples below illustrate these two approaches.

access.key

character string. Supply your ACLED access key. The access key can also be set as an environment variable using Sys.setenv(ACCESS_KEY="your.access.key"), in which case this argument can be skipped. Usage examples below illustrate these two approaches.

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 (see ACLED's API user guide for details on region codes and names). See the details below for information on how the arguments "country" and "region" interact.

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: region, country, year, event_date, source, admin1, admin2, admin3, location, event_type, sub_event_type, interaction, fatalities.

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.

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.

The user's registered email address and ACLED access key can be supplied as strings directly to their respective arguments, or set in advance as environment variables using

Sys.setenv(EMAIL_ADDRESS="your.email.address") and

Sys.setenv(ACCESS_KEY="your.access.key").

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).

The ACLED API combines the country argument and the region argument with a logical AND operator. Therefore, specifying e.g. 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.

Value

A data frame containing ACLED events.

Author(s)

Christoph Dworschak
Website: https://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("EMAIL_ADDRESS"),
  access.key = Sys.getenv("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)

[Package acled.api version 1.1.3 Index]