UCDP Application Programming Interface (API)

The main maintainer of the API is Mert Can Yilmaz.

In keeping with UCDP's commitment to open and accessible research infrastructure, the API is free of charge. To safeguard service stability and protect against unintended overuse and automated bot traffic, authenticated access via token was introduced in February 2026. To use the API, please contact the API maintainer to request an access token. In your email, briefly describe your research project and/or intended use of the data.

An API (Application Programming Interface) enables direct programmatic access to our systems, allowing scripts, programs, database queries, do-files, and similar tools to extract and process data without manual intervention. Through the UCDP API, researchers can obtain, process, and subset UCDP data dynamically with only a few lines of code, eliminating the need to download or maintain local copies of the data.

The API is designed to substantially reduce the overhead associated with working with UCDP data. Data management tasks that previously demanded extensive code, considerable computational resources, and careful manual handling can be delegated entirely to our servers. Researchers are thus relieved of the need to maintain local copies of the data, manage version histories, or guard against unintended modifications to source files. All data is retrieved directly and freshly from a centrally maintained, authoritative source that remains unaffected by client-side operations.

The API fully supports versioning. Each API call — expressed as a URL — is guaranteed to return the same data at the same version indefinitely. Researchers who include API calls in their replication materials can therefore be confident that the same data will be returned upon future retrieval, even years after the original query. To ensure this guarantee holds, we require that a version number be specified with every API call.

Once issued, the token must be submitted with each request as an HTTP header named x-ucdp-access-token:

curl -H "x-ucdp-access-token: YOUR-TOKEN" \
     "https://ucdpapi.pcr.uu.se/api/gedevents/25.1?pagesize=100"

import requests

TOKEN = "YOUR-TOKEN"
headers = {"x-ucdp-access-token": TOKEN}

url = "https://ucdpapi.pcr.uu.se/api/gedevents/25.1"
params = {"pagesize": 100, "page": 1}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(f"Total events: {data['TotalCount']}")
for event in data["Result"]:
    print(event["id"], event["country"])

library(httr)
library(jsonlite)

TOKEN <- "YOUR-TOKEN"

url <- "https://ucdpapi.pcr.uu.se/api/gedevents/25.1"
response <- GET(
  url,
  add_headers("x-ucdp-access-token" = TOKEN),
  query = list(pagesize = 100, page = 1)
)

data <- fromJSON(content(response, "text", encoding = "UTF-8"))
cat("Total events:", data$TotalCount, "\n")
print(head(data$Result[, c("id", "country")]))

* Requires the -jsonio- package: net install jsonio, from("https://raw.githubusercontent.com/mdroste/stata-jsonio/master/")

local token "YOUR-TOKEN"
local url "https://ucdpapi.pcr.uu.se/api/gedevents/25.1?pagesize=100"

jsonio get, url("`url'") ///
    headers("x-ucdp-access-token: `token'")

* Results are stored in r(json) and can be parsed with jsonio kv
jsonio kv, from(r(json)) fromtype(object)

As standard browser address bars do not support custom HTTP headers, token-protected endpoints cannot be invoked directly from a browser URL. Access must therefore be established programmatically — for example, via curl, Python's requests, R's httr, Stata's jsonio, or any HTTP client capable of transmitting custom headers.

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: 25.1

The latest versions of UCDP GED Candidate:
Monthly release: 26.0.1
Quarterly release: 25.01.25.12

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: 25.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.

The following examples illustrate the structure of API calls and the format of returned output. Note that token-protected requests require a programmatic client capable of sending custom HTTP headers (see above). For example, this link:

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

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

{
  "TotalCount": 385918,
  "TotalPages": 385918,
  "PreviousPageUrl": null,
  "NextPageUrl": "https://ucdpapi.pcr.uu.se/api/gedevents/25.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-06",
      "date_end": "2002-10-06",
      "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/25.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 far outside the bounds of the data may return a server error rather than an empty set. It is recommended to iterate using the TotalPages value in the response to stay within valid bounds.

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/25.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/25.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/25.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/25.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/25.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/25.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

Usage is governed by the following limit:

5,000 requests per day. Errors count towards the limit.

To request a token, or to have a token revoked or reissued for security reasons, please contact the API maintainer.

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 25.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.0.11 24.0.12 24.01.24.03 24.01.24.06 24.01.24.09 24.01.24.12

26.0.1

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 25.1

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