UCDP API

Welcome to the UCDP API.

The main maintainer of the API is Mihai Croicu :

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 :

http://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). Only HTTP is supported; HTTPS support will be added in the future.

Currently, available resources are:

The UCDP Georeferenced Event Dataset (UCDP GED), which is labeled in the API as:
gedevents
The following versions are available:
5.0 17.1 17.2 18.1 19.1

 

as well as the yearly UCDP datasets:

UCDP/PRIO Armed Conflict Dataset referred to as:
ucdpprioconflict
UCDP Dyadic Dataset referred to as:
dyadic
UCDP Non-State Conflict Dataset:
nonstate
UCDP One-Sided Violence Dataset:
onesided
UCDP Battle Related Deaths Dataset:
battledeaths

Versions 17.2 18.1 and 19.1 of the yearly datasets is available.

 

You need to specify the version you want explicitly.

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:
http://ucdpapi.pcr.uu.se/api/gedevents/17.2?pagesize=1
will output each GED event as its own page, like this:
{
  "TotalCount": 135181,
  "TotalPages": 135181,
  "PreviousPageUrl": "",
  "NextPageUrl": "http://ucdpapi.pcr.uu.se/api/gedevents/17.2?pagesize=1&page=1",
  "Result": [
    {
      "id": 85670,
      "relid": "",
      "year": 1989,
      "active_year": true,
      "code_status": "Clear",
      "type_of_violence": 3,
      "conflict_dset_id": "319",
      "conflict_new_id": 519,
      "conflict_name": "Sikh insurgents - Civilians",
      "dyad_dset_id": "319",
      "dyad_new_id": 986,
      "dyad_name": "Sikh insurgents - Civilians",
      "side_a_dset_id": "319",
      "side_a_new_id": 319,
      "side_a": "Sikh insurgents",
      "side_b_dset_id": "9999",
      "side_b_new_id": 1,
      "side_b": "Civilians",
      "number_of_sources": -1,
      "source_article": "Reuters 1/1/1989",
      "source_office": "",
      "source_date": "",
      "source_headline": "",
      "source_original": "police",
      "where_prec": 1,
      "where_coordinates": "Chawinda Devi village",
      "where_description": "",
      "adm_1": "Punjab State",
      "adm_2": "Amritsar district",
      "latitude": 31.714790,
      "longitude": 75.082214,
      "geom_wkt": "POINT (75.082214 31.714790)",
      "priogrid_gid": 175471,
      "country": "India",
      "country_id": 750,
      "region": "Asia",
      "event_clarity": 1,
      "date_prec": 1,
      "date_start": "1989-01-01T00:00:00",
      "date_end": "1989-01-01T00:00:00",
      "deaths_a": 0,
      "deaths_b": 0,
      "deaths_civilians": 3,
      "deaths_unknown": 0,
      "best": 3,
      "high": 3,
      "low": 3,
      "GWNoA": "",
      "GWNoB": ""
    }
  ]
}

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:

http://ucdpapi.pcr.uu.se/api/gedevents/17.2?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 128.264 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:

Parameter Type Multiple Dataset Variable Comment
Id Integer Yes id
Country Integer Yes country_id Gleditsch and Ward country codes
Geography String No latitude, longitude Two coordinates (upper left and lower right in the format y0 x0,y1 x1) describing the bounding box to be used to select GED events.
The first point should be the South-Western point whereas the second point should be the North-Eastern point.
Note that you have to use: latitude longitude,latitude longitude NOT longitude latitude, as expected by some GIS applications.
StartDate String No date_end YYYY-MM-DD
EndDate String No date_end YYYY-MM-DD
TypeOfViolence Integer Yes type_of_violence
Dyad Integer Yes date_new_id Uses the NEW format for Dyad IDs introduced with GED at version 5.0 and rolled out in all UCDP datasets with version 17.1. Thus, Government of Mali - FIAA is dyad 801 and not 72.
Actor Integer Yes side_a_new_id OR side_b_new_id Will retrieve all events having the given actor as one of the sides. Uses the NEW format for Actor IDs introduced with GED at version 5.0 and rolled out in all UCDP datasets with version 17.1. Thus, the Government of Mali is 72 AND NOT 432. See the actor list available on http://ucdp.uu.se/downloads for details

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

http://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:

http://ucdpapi.pcr.uu.se/api/gedevents/17.2?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:

http://ucdpapi.pcr.uu.se/api/gedevents/17.2?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:
http://ucdpapi.pcr.uu.se/api/gedevents/17.2?pagesize=100&Geography=40 -75,41 -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:

http://ucdpapi.pcr.uu.se/api/gedevents/17.2?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):
Parameter Type Multiple Dataset Variable Comment
Country Integer Yes gwno_loc Gleditsch and Ward country codes
Conflict Integer Yes conflict_id
Year Integer Yes year YYYY
ConflictIncompatibility Integer Yes incompatibility
ConflictType Integer Yes type_of_conflict

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

Parameter Type Multiple Dataset Variable Comment
Dyad Integer Yes dyad_id
Conflict Integer Yes conflict_id
Country Integer Yes gwno_loc Gleditsch and Ward country codes
Year Integer Yes year YYYY
ConflictIncompatibility Integer Yes incompatibility
ConflictType Integer Yes type_of_conflict

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

Parameter Type Multiple Dataset Variable Comment
Country Integer Yes gwno_location Gleditsch and Ward country codes
Conflict Integer Yes conflict_id
Org Integer Yes org
Year Integer Yes year YYYY

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

Parameter Type Multiple Dataset Variable Comment
Dyad Integer Yes actor_id
Country Integer Yes gwno_location Gleditsch and Ward country codes
Year Integer Yes year YYYY

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

http://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:

http://ucdpapi.pcr.uu.se/api/nonstate/17.2?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:

http://ucdpapi.pcr.uu.se/api/ucdpprioconflict/17.2?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 the 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 37 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

UCDP plans on making it even easier to interface for users and researchers to use our data dynamically in their projects. We expect to release native packages/libraries for R, Python and Stata in 2018-2019.

Until then, the API can, of course, 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.