acledR (version 0.1.0)

acled_api: Request data from ACLED API

Description

This function allows users to easily request data from the ACLED API. Users can include variables such as country, regions, dates of interest and the format (monadic or dyadic). The function returns a tibble of the desired ACLED events.

Usage

acled_api(
  email = NULL,
  key = NULL,
  country = NULL,
  regions = NULL,
  start_date = floor_date(Sys.Date(), "year") - years(1),
  end_date = Sys.Date(),
  timestamp = NULL,
  event_types = NULL,
  population = "none",
  inter_numeric = FALSE,
  monadic = FALSE,
  ...,
  acled_access = TRUE,
  prompt = TRUE,
  log = FALSE
)

Value

Returns a tibble of of ACLED events.

Arguments

email

character string. Email associated with your ACLED account registered at https://developer.acleddata.com.

key

character string. Access key associated with your ACLED account registered at https://developer.acleddata.com.

country

character vector. Default is NULL, which will return events for all countries. Pass a vector of countries names to retrieve events from specific countries. The list of ACLED countries. names may be found via acledR::acled_countries.

regions

vector of region names (character) or region codes (numeric). Default is NULL, which will return events for all regions. Pass a vector of regions names or codes to retrieve events from countries. within specific regions. The list of ACLED regions may be found via acledR::acled_regions.

start_date

character string. Format 'yyyy-mm-dd'. The earliest date for which to return events. The default is 1997-01-01, which is the earliest date available.

end_date

character string. Format 'yyyy-mm-dd'. The latest date for which to return events. The default is Sys.Date(), which is the most present date.

timestamp

numerical or character string. Provide a date or datetime written as either a character string of yyyy-mm-dd or as a numeric Unix timestamp to access all events added or updated after that date.

event_types

vector of one or more event types (character). Default is NULL, which will return data for all event types. To reurn data for only specific event types, request one or more of the following options (not case sensitive): Battles, Violence against civilians, Protests, Riots, Strategic Developments, and Explosions/Remote violence.

population

character. Specify whether to return population estimates for each event. It accepts three options: "none" (default), "best", and "full".

inter_numeric

logical. If FALSE (default), interaction code columns (inter1, inter2, and interaction) returned as strings describing the actor types/interactions. If TRUE, the values are returned as numeric values.

monadic

logical. If FALSE (default), returns dyadic data. If TRUE, returns monadic actor1 data.

...

string. Any additional parameters that users would like to add to their API calls (e.g. interaction or ISO)

acled_access

logical. If TRUE (default), you have used the acled_access function and the email and key arguments are not required.

prompt

logical. If TRUE (default), users will receive an interactive prompt providing information about their call (countries requested, number of estimated events, and number of API calls required) and asking if they want to proceed with the call. If FALSE, the call continues without warning, but the call is split and returns a message specifying how many calls are being made.

log

logical. If TRUE, it provides a dataframe with the countries and days requested, and how many calls it entails. The dataframe is provided INSTEAD of the normal ACLED dataset.

See Also

• ACLED API guide. https://apidocs.acleddata.com/

Other API and Access: acled_access(), acled_deletions_api(), acled_update()

Examples

if (FALSE) {

# Get all the events coded by ACLED in Argentina from 01/01/2022 until 02/01/2022
# in dyadic-wide form
argen_acled <- acled_api(
  email = "your_email", key = "your_key",
  country = "Argentina", start_date = "2022-01-01", end_date = "2022-02-01",
  acled_access = FALSE
)

# tibble with all the events from Argentina where each row is one event.
argen_acled

# Get all events coded by ACLED in the Caribbean from 01/01/2022 to 10/01/2022
# in monadic-long form using email and key saved in environment

acled_access(email = "your_email", key = "your_key")
carib_acled <- acled_api(
  regions = "Caribbean", start_date = "2022-01-01",
  end_date = "2022-01-10", monadic = TRUE, acled_access = TRUE
)

## Tibble with all the events from the Caribbean where each row is one actor
carib_acled
}