Welcome to the UCDP API

---

The main maintainer of the API is Stina Högbladh.

An API (Application Programming Interface) allows your systems (scripts, programs, database queries, do-files etc.) to interface directly with our systems in order to extract and process data. Using the UCDP API you will be able to, via just a few lines of code, have your programs or scripts obtain, process and subset UCDP data dynamically, without ever needing to download a copy of the data manually.

With the API we expect and hope to ease the burden of using UCDP data. With only a few lines of code, we expect significant data management work that took hundreds of lines and required significant effort and event computational resources to be shifted to our servers. Further, we hope to alleviate the burden of doing manual data versioning with our data on your side; with the API you will no longer be having to keep track of various versions and modifications of our datasets on your computers. Further, you no longer need to worry that your script may have affected the original data files in any way - the data is always taken anew at each API call from a guaranteed correct and complete data source that cannot be affected by your script in any way.

Moreover, the API completely integrates and supports versioning. Thus, an API call (which takes the form of a URL) will always point to the exact same data, and to the exact version of the data. I.e., if you include an API call to a resource in your replication file, we guarantee that the same data will be returned to you in the future (even 5 or 10 years down the line). Thus, we require that you specify the version number of the data you want with each API call.

Like all UCDP products, the API is free of charge. However, to maintain systems' and servers' integrity from misbehaving scripts, some limits are imposed on usage, limits which are described below.

Description

The API is fully RESTful, takes the form of simple HTTP requests, and returns JSON, having this general format:

https://ucdpapi.pcr.uu.se/api/<resource>/<version>?<pagesize=x>&<page=x>

The API returns standard JSON objects that can be processed with ease in your script (see examples below).

Currently, available resources are:

The UCDP Georeferenced Event Dataset (UCDP GED), which is labeled in the API as:

gedevents

The latest version of UCDP GED: 24.1

The latest versions of UCDP GED Candidate: Monthly release: 24.0.10 Quarterly release: 24.01.24.09

The yearly UCDP datasets:

UCDP/PRIO Armed Conflict Dataset which is labeled in the API as:

ucdpprioconflict

UCDP Dyadic Dataset which is labeled in the API as:

dyadic

UCDP Non-State Conflict Dataset which is labeled in the API as:

nonstate

UCDP One-Sided Violence Dataset which is labeled in the API as:

onesided

UCDP Battle Related Deaths Dataset which is labeled in the API as:

battledeaths

The latest version of the yearly datasets: 24.1

Due to the large size of UCDP resources (especially GED), the API implements and requires paging. As such, the API will return all the rows in your query at once, but will do so in a number pages of a fixed maximum number of rows.

You may iterate through the pages. Each response will provide you with the current page number, the total number of pages, the total number of rows, as well as links to the next and previous page

You may specify the page size (number of rows to be returned in each page) depending on your requirements and computational setup. A page may, however, be between 1 and 1000 rows. If you specify a page size over 1000, it will return the first 1000 rows of the result and truncate the rest.

The API is accessible through any HTTP connection, including a normal web-browser. The following examples can be clicked and will produce output (an array of JSON objects representing GED events) in your browser. We encourage you to click them to understand and explore the output. For example, this link:

https://ucdpapi.pcr.uu.se/api/gedevents/24.1?pagesize=1

will output each GED event as its own page, like this:

{
  "TotalCount": 349733,
  "TotalPages": 349733,
  "PreviousPageUrl": null,
  "NextPageUrl": "https://ucdpapi.pcr.uu.se/api/gedevents/24.1?pagesize=1&page=1",
  "Result": [
    {
      "id": 2,
      "relid": "USA-2002-1-878-0",
      "year": 2002,
      "active_year": true,
      "code_status": "Clear",
      "type_of_violence": 1,
      "conflict_dset_id": "418",
      "conflict_new_id": 418,
      "conflict_name": "United States of America: Government",
      "dyad_dset_id": "878",
      "dyad_new_id": 878,
      "dyad_name": "Government of United States of America - al-Qaida",
      "side_a_dset_id": "3",
      "side_a_new_id": 3,
      "side_a": "Government of United States of America",
      "side_b_dset_id": "769",
      "side_b_new_id": 769,
      "side_b": "al-Qaida",
      "number_of_sources": 4,
      "source_article": "\"Jane's Intelligence Review,2006-01-13,Internal politics complicate counterterrorism in Yemen\";\"Cedre,2004-05-02,Limburg\";\"BBC,2006-10-01,Al-Qaeda fugitive killed in Yemen\";\"National Commission on Terrorist Attacks Upon the United States,2004-08-24,5 AL QAEDA AIMS AT THE AMERICAN HOMELAND\"",
      "source_office": "Jane's Intelligence Review;Cedre;BBC;National Commission on Terrorist Attacks Upon the United States",
      "source_date": "2006-01-13;2004-05-02;2006-10-01;2004-08-24",
      "source_headline": "Internal politics complicate counterterrorism in Yemen;Limburg;Al-Qaeda fugitive killed in Yemen;5 AL QAEDA AIMS AT THE AMERICAN HOMELAND",
      "source_original": "US prosecutors, National Commission on Terrorist Attacks Upon the United States",
      "where_prec": 2,
      "where_coordinates": "Ash Shiḩr town",
      "where_description": "3 km from the Ash Shihr oil terminal (Hadramawt province)",
      "adm_1": "Ḩaḑramawt governorate",
      "adm_2": "Ash Shiḩr district",
      "latitude": 14.760260,
      "longitude": 49.605370,
      "geom_wkt": "POINT (49.60537 14.76026)",
      "priogrid_gid": 150940,
      "country": "Yemen (North Yemen)",
      "country_id": 678,
      "region": "Middle East",
      "event_clarity": 1,
      "date_prec": 1,
      "date_start": "2002-10-06T00:00:00",
      "date_end": "2002-10-06T00:00:00",
      "deaths_a": 0,
      "deaths_b": 1,
      "deaths_civilians": 1,
      "deaths_unknown": 0,
      "best": 2,
      "high": 2,
      "low": 2,
      "gwnoa": "2",
      "gwnob": null
    }
  ]
}
            

To access page 295 of this result set, you may either use the NextPageUrl property to iterate until page 295, or simply give the page number directly like this:

https://ucdpapi.pcr.uu.se/api/gedevents/24.1?pagesize=1&page=295

We guarantee the consistency of the result-set order within a session. However, the order of events is meaningless and determined by an internal mechanism not connected to the dataset in any way. If your application depends on ordered sets, you will have to use the filtering mechanisms described below.

Requesting a page outside the bounds of the data, e.g. page 100000 for a page-size of 100 (thus the 10.000.000 event and onwards in a dataset with 225.385 events) will produce an empty set.

 

Filtering and Subsetting

UCDP GED

You may use the following filters and parameters to request only a subset of UCDP GED:

When filtering is employed, the general form of the API call is described below:

https://ucdpapi.pcr.uu.se/api/<resource>/<version>?<pagesize=x>&<page=x>[&<filter>=<condition1,[condition2]>...]

Multiple filters can be used together, see details below.

• A note on the StartDate and EndDate parameters: they both operate on date_end.

StartDate will give you all the events that have a date_end (i.e. that have definitely happened by that date) equal or greater to the specified date, to the end of the dataset time-span. For example, if you use this filter:

StartDate=2000-01-01

you will receive all the events taking place between 1 January 2000 and 31 December 2015.

EndDate will give you all the events from the beginning of the dataset's time span to the specified date_end (i.e. the date by which those events have definitely happened by that date). For example, if you use this filter:

EndDate=2000-01-01

you will receive all the events taking place between 1 January 1989 and 1 January 2000.

You can combine these two filters to get a fixed time span. Using:

 StartDate=2000-01-01&EndDate=2007-10-12

will yield all the events between 1 January 2000 and 12 October 2007.

For those variables permitting multiple values, you may request data that fulfills ANY of the conditions specified (boolean OR). You need to separate the conditions by a comma (,). For example, you may issue this request:

https://ucdpapi.pcr.uu.se/api/gedevents/24.1?pagesize=100&Country=90,91,92

This will request all the events taking place in either Guatemala (id:90), Honduras (id:91) or El Salvador (id:92).

You can use multiple filters at once, each filter separated by the http standard ampersand (the & character). The result set will contain all the events fulfilling ALL the criteria at the same time (boolean AND. For example, you may issue this request:

https://ucdpapi.pcr.uu.se/api/gedevents/24.1?pagesize=100&Country=365,369&StartDate=2014-01-15&EndDate=2015-02-28&TypeOfViolence=1,3

you will receive all the state-based and one-sided events in either Russia or Ukraine taking place between 15 January 2014 and 31 December 2015.

Similarly, using:

https://ucdpapi.pcr.uu.se/api/gedevents/24.1?pagesize=100&Geography=40%20-75,41%20-73&StartDate=2001-09-11&EndDate=2001-09-11

will give you all UCDP events coupled with the 9/11 events in New York City. Note that in some applications you may have to escape the space characters and replace them with the %20 escape code.

Similarly, using:

https://ucdpapi.pcr.uu.se/api/gedevents/24.1?pagesize=100&Country=645&Actor=234

will return all the activity of the Islamic State (IS, ISIL, ISIS, Daesh etc.) in Iraq.

The behaviour in case of errors is this:
Attempting to use a filter that does not exist will result in that filter being completely ignored.
Attempting to use an out-of-bounds or wrong value for filtering will result in an empty set being returned.

Yearly Datasets

You may use the following filters and parameters to request only a subset of the UCDP/PRIO Conflict Dataset (ucdpprioconflict):

You may use the following filters and parameters to request only a subset of the UCDP Dyadic Dataset (dyadic):

You may use the following filters and parameters to request only a subset of the UCDP Battle Related Deaths Dataset (battledeaths):

You may use the following filters and parameters to request only a subset of the UCDP Non-State Conflict Dataset (nonstate):

You may use the following filters and parameters to request only a subset of the UCDP One-Sided Violence Dataset (onesided):

When filtering is employed, the general form of the API call is described below:

https://ucdpapi.pcr.uu.se/api/<resource>/<version>?<pagesize=x>&<page=x>[&<filter>=<condition1,[condition2]>...]

All filters for yearly datasets permit multiple values - you may request data within a filter that fulfills ANY of the conditions specified (boolean OR). You need to separate the conditions by a comma (,). For example, you may issue this request:

https://ucdpapi.pcr.uu.se/api/nonstate/24.1?pagesize=100&Country=90,91,92

This will request a list of all the non-state conflicts taking place in either Guatemala (id:90), Honduras (id:91) or El Salvador (id:92).

You can use multiple filters at once. Each filter must be separated by the http standard ampersand (the & character). The result set will contain all the events fulfilling ALL the criteria at the same time (boolean AND). For example, you may issue this request:

https://ucdpapi.pcr.uu.se/api/ucdpprioconflict/24.1?pagesize=100&Country=365,369&year=2014,2015

you will receive all the list of state-based conflicts taking place in Russia or Ukraine in 2014 or 2015.

The behaviour in case of errors is this:
Attempting to use a filter that does not exist will result in that filter being completely ignored.
Attempting to use an out-of-bounds or wrong value for filtering will result in an empty set being returned.

 

Access Quotas and Restrictions

To reduce the incidence of security attacks, as well as catch misbehaving scripts (such as infinite loops) inherent in development, we have imposed the following usage limits:

1. A limit of 5000 requests per day, 1 request being one call of ucdpapi.pcr.uu.se by any means (i.e. 1 page). Errors are counted towards the limit to prevent DoS attacks.
2. A limit of 1000 events/page for GED and 1000 rows/page for the yearly dataset .

This allows you to download the entirety of GED approximately 15 times per day (and each of the yearly datasets approximately 2500 times per day). If you need more downloads, or if you want to implement a live-system (e.g. a visualization on a webpage using and showing UCDP data) a token system has been implemented that cancels both the need for paging and the download limit. All counters reset at midnight UTC.

Please contact the maintainer if you need tokens or if you need a token revoked/reissued for security reasons.

 

Other tools connected to the API

The API can be used via packages able to interface with RESTful APIs such as requests in Python, net/http in Ruby, jsonlite in R, insheetjson in STATA, the curl methods in the default library in PHP etc.

 

Available datasets

For UCDP GED, the following versions are available:

5.0 17.1 17.2 18.1 19.1 652.1601.1911 20.1 21.1 22.1 23.1 24.1

For UCDP GED Candidate, the following versions are available:

18.0.1 18.0.2 18.0.3 18.0.4 18.0.5 18.0.6 18.0.7 18.0.8 18.0.9 18.0.10 18.0.11 18.0.12

19.0.1 19.0.2 19.0.3 19.0.4 19.0.5 19.0.6 19.0.7 19.0.8 19.0.9 19.0.10 19.0.11 19.0.12

20.0.1 20.0.2 20.0.3 20.0.4 20.0.5 20.0.6 20.0.7 20.0.8 20.0.9 20.0.10 20.0.11 20.0.12 20.01.20.06 20.01.20.09 20.01.20.12

21.0.1 21.0.2 21.0.3 21.0.4 21.0.5 21.0.6 21.0.7 21.0.8 21.0.9 21.0.10 21.0.11 21.0.12 21.01.21.03 21.01.21.06 21.01.21.09 21.01.21.12

22.0.1 22.0.2 22.0.3 22.0.4 22.0.5 22.0.6 22.0.7 22.0.8 22.0.9 22.0.10 22.0.11 22.0.12 22.01.22.03 22.01.22.06 22.01.22.09 22.01.22.12

23.0.1 23.0.2 23.0.3 23.0.4 23.0.5 23.0.6 23.0.7 23.0.8 23.0.9 23.0.10 23.0.11 23.0.12 23.01.23.04 23.01.23.06 23.01.23.09 23.01.23.12

24.0.1 24.0.2 24.0.3 24.0.4 24.0.5 24.0.6 24.0.7 24.0.8 24.0.9 24.0.10 24.01.24.03 24.01.24.06 24.01.24.09

For the yearly datasets such as UCDP/PRIO Armed Conflict Dataset, UCDP Dyadic Dataset, UCDP Non-State Conflict Dataset, UCDP One-Sided Violence Dataset, and UCDP Battle Related Deaths Dataset, the following versions are available:

17.2 18.1 19.1 20.1 21.1 22.1 23.1 24.1

All codebooks and version histories for UCDP's datasets can be downloaded from the UCDP Dataset Download Center.