Get Started

In this section, you can learn the basics of using the ACLED API to access ACLED data. You will start by creating your account and generating a unique personal access key. You will then learn how to use that key to request data using an API call.

Getting your API key

Login/Register

ACLED’s API is a RESTful API that uses basic HTTP authentication. In simple terms, this means that you need a unique personal access key to download ACLED data. To get an access key, you will first need to register an account through ACLED’s Access Portal, instructions for which can be found here. You are encouraged to use your institutional or organizational email address rather than a personal one, in order to ensure you benefit from any affiliated access privileges.

Note: you should be able to generate your access key and download data via the Export Tool or API after verifying your email address and accepting the Terms of Use. If you run into any issues when downloading, please reach out to [email protected].

After you register, your user type will determine your access permissions. The default access limits for each account type are below. Please note that Public and Corporate access limits are cumulative across an organization.

Warning: package 'dplyr' was built under R version 4.2.3

Table 1: Table of access limits to all endpoints except CAST
Public Sector	Civil Society/Academic	Corporate
Six downloads per year in total (from date of registration).	Unlimited downloads of the full global dataset.	Three downloads per year in total (from date of registration).
Access to real-time data through the Export Tool (API on request).	Access to real-time data through the Export Tool (API on request).	Access to real-time data through the Export Tool (API on request).
Access to three years of historical data (when available).	Access to all historical data (when available).	Access to one year of historical data (when available).

Once registered, you can keep track of your data usage in the developer portal’s Usage section. If you need access to ACLED data beyond the access limits for your account type, please contact ACLED’s Access team

After setting up your account, you can generate an access key, which you will need in order to download data. You can get started by visiting ACLED’s Developer Portal and signing in with your email and password when prompted to do so.

Developer interface

Once you log in to the developer portal, you will see the following page:

To receive your access key, click on “Add New Key”. You will see the following page that displays your access key:

Please remember to copy the key and save it in a safe place. You will not be able to view this key again.

Setting up an API call & building a URL

To execute an API call (i.e. to request data), you will use your access key, along with other information, to create a URL. You can use this URL to request data via your internet browser or through programming languages such as R or Python, a step which is covered in the individual endpoint tabs (e.g. ACLED endpoint section).

The base URL - From whom are you requesting data?

An API call is simply a request sent from one computer to another. Accordingly, the first step in building the URL that you will use to execute your API call is specifying where you would like to send your request. To access ACLED data, your computer must send a request to ACLED’s server, which you can specify using the ACLED API’s base URL:

https://api.acleddata.com/

Every request you make to the ACLED API will start with this base URL.

The endpoint - Which ACLED dataset would you like to access?

After stating that you would like to request data from ACLED’s server, you must also specify which data (or “endpoint”) you are requesting. In practical terms, which ACLED dataset are you interested in accessing? Available endpoints/datasets include:

Be sure to click through ACLED’s endpoint links to understand your options. If you want to access the core dataset of political violence, demonstration, and strategic development events, then you should use the ACLED endpoint.

Once you have selected an endpoint, you can add it to the base URL. For example, if you are requesting data from the ACLED endpoint, your URL should now look like this:

https://api.acleddata.com/acled/

The response format - How would you like your data to be formatted?

An important element to consider when setting up your API call is the format of the data you want to receive. As covered in the Advanced concepts section, there are four file types which you can request: JSON, CSV,XML, and TXT.

You can specify your desired data format by adding read + {the extension of the format you want}, followed by ? to your URL. The only exception is JSON format, which is the default option, and therefore only requires you to write read?

For example, if you want your data in CSV format, your URL should now appear as:

https://api.acleddata.com/acled/read.csv?

Authentication - Who is requesting the data?

Your URL also needs to include your authentication information so that ACLED’s server knows who is requesting data. You can include this information by adding key and email information to your URL in the following format: key=your_key&email=your_email.

Your URL should now look something like this:

https://api.acleddata.com/acled/read.csv?key=your_key&email=your_email**

Note: Please be sure to enter your unique key and email address instead of the generic key and email address used in this example. If you try to use the example URL without your specific credentials then ACLED’s API will return an error and you will not receive any data.

Query filters - Which data do you want?

The URL you have built will now return data. However, the ACLED API has a default row limit of 5000, meaning this URL will execute an API call that only returns the first 5000 rows of the requested dataset. (For more information on this, see the Limits section below.)

In almost all cases, users only need a subset of the entire dataset.

Instead of arbitrarily requesting the first 5000 rows of data, you can use query filters to specify which data you want to receive.

For instance, imagine you are interested in investigating events in the country of Georgia between 2022-01-01 and 2023-02-01. Rather than downloading the entire dataset and then finding the relevant events within it, you can use query filters to request only the specific events that meet your criteria. In this case, you should use the event_date and country query filters. You can learn the basics of applying query filters in the examples below, but for a more in-depth guide, visit our ACLED endpoint section.

You can start by applying a query filter to specify the country of interest. The country query filter is an “=” type, which will match your request to an exact value in the dataset. For instance, if you include country=Georgia in your URL, you will receive all events in which the country column exactly matches “Georgia”.

https://api.acleddata.com/acled/read.csv?key=your_key&email=your_email&country=Georgia

Next, you can specify your desired date range. You can specify a particular date by using the event_date filter, which is also of “=” type. For example, if you include ...&event_date=2023-02-01 in your URL, you will receive a dataset containing events that occurred on the 1st of February 2023.

In all likelihood, rather than requesting events from a specific date, you will want to request events occurring across a date range. You can do so by changing the query type. Specifically, you can add the _where suffix to your query filter and then select the type of query you would like to use (e.g., BETWEEN allows you to filter for anything between two values separated by |). See Advanced concepts section for more details on building complex queries.

Your URL is now requesting only the desired and specific subset of ACLED data:

https://api.acleddata.com/acled/read.csv?key=your_key&email=your_email&country=Georgia&event_date=2022-01-01|2023-02-01&event_date_where=BETWEEN

Remember: If you have more than one query filter (e.g. one for country and one for event_date), they should be separated by the & symbol.

Limits

Your URL is now usable. It contains the base URL, the endpoint, your authentication credentials, and appropriate query filters. However, even when using query filters, the returned dataset may be very large. If you do not need every event defined by your query filters, you can limit the size of the returned file. In particular, you can specify the number of events in the returned data by including a limit statement in your URL (e.g., limit=2000 means you will receive data for 2000 events). Without a ‘limit’ in your URL, ACLED’s API will return a maximum of 5000 events. In cases where you are expecting events beyond the default limit, you are advised to use pagination which allows you to split your call into multiple smaller ones and ensure your call executes successfully. These calls do not count toward your API rate limits. For more on pagination and limits, see the Advanced concepts section.

In the example you have been working through, you are requesting data from a very limited date range in a country with relatively few events. You therefore might only expect to receive several hundred rows of data – far fewer than ACLED’s 5000 row default. You probably do not need to include a limit for such a restricted API call, but if desired you could add a reasonable limit to your URL:

https://api.acleddata.com/acled/read.csv?key=your_key&email=your_email&country=Georgia&event_date=2022-01-01|2023-02-01&event_date_where=BETWEEN&limit=3000

Executing the call

Congratulations – you have built your first URL to request ACLED data! You can now execute your API call and receive specific data from ACLED’s API. The easiest way to execute your API call is to simply copy and paste the URL you have built into your browser. If your call is successful, your data will start downloading in the specified file format.

You can now examine the data you received (for the sake of better readability, we removed the notes column in this example, and reduced the number of rows):

event_id_cnty	event_date	year	time_precision	disorder_type	event_type	sub_event_type	actor1	assoc_actor_1	inter1	interaction	iso	region	country	admin1	admin2	location	latitude	longitude	geo_precision	source	source_scale	notes	tags	timestamp
GEO3998	2023-02-01	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)	Labor Group (Georgia)	6	60	268	Caucasus and Central Asia	Georgia	Imereti	Kutaisi City	Kutaisi	42.2639	42.6999	1	RFE/RL	International	[...] Notes truncated for this example	crowd size=no report	1675798462
GEO3999	2023-02-01	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)	Labor Group (Georgia); Health Workers (Georgia)	6	60	268	Caucasus and Central Asia	Georgia	Tbilisi	Tbilisi	Tbilisi	41.7183	44.8306	1	Interpressnews	National	[...] Notes truncated for this example	crowd size=no report	1675798462
GEO4002	2023-02-01	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)		6	60	268	Caucasus and Central Asia	Georgia	Tbilisi	Tbilisi	Tbilisi	41.7183	44.8306	1	Netgazeti.ge	National	[...] Notes truncated for this example	crowd size=no report	1675798462
GEO4001	2023-01-31	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)		6	60	268	Caucasus and Central Asia	Georgia	Autonomous Republic of Adjara	Batumi City	Batumi	41.6423	41.6339	1	Caucasian Knot	International	[...] Notes truncated for this example	crowd size=no report	1702344160
GEO4000	2023-01-29	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)		6	60	268	Caucasus and Central Asia	Georgia	Autonomous Republic of Adjara	Batumi City	Batumi	41.6423	41.6339	1	Caucasian Knot	International	[...] Notes truncated for this example	crowd size=around 100	1702344161
GEO3997	2023-01-26	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)		6	60	268	Caucasus and Central Asia	Georgia	Shida Kartli	Gori City	Gori	41.9842	44.1158	1	Rustavi 2	National	[...] Notes truncated for this example	crowd size=no report	1675191965
GEO3994	2023-01-24	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)	Protesters (Russia); Protesters (Iran)	6	60	268	Caucasus and Central Asia	Georgia	Tbilisi	Tbilisi	Tbilisi	41.7183	44.8306	1	Netgazeti.ge	National	[...] Notes truncated for this example	crowd size=no report	1675191965
GEO3996	2023-01-22	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)	Protesters (Ukraine)	6	60	268	Caucasus and Central Asia	Georgia	Tbilisi	Tbilisi	Tbilisi	41.7183	44.8306	1	Agenda.ge	National	[...] Notes truncated for this example	crowd size=no report	1680633878
GEO3995	2023-01-22	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)	Protesters (Ukraine)	6	60	268	Caucasus and Central Asia	Georgia	Autonomous Republic of Adjara	Batumi City	Batumi	41.6423	41.6339	1	Caucasian Knot	International	[...] Notes truncated for this example	crowd size=no report	1702344161
GEO3993	2023-01-21	2023	1	Demonstrations	Protests	Peaceful protest	Protesters (Georgia)	Protesters (Russia)	6	60	268	Caucasus and Central Asia	Georgia	Tbilisi	Tbilisi	Tbilisi	41.7183	44.8306	1	Caucasian Knot	International	[...] Notes truncated for this example	crowd size=several dozen	1702344161

Congratulations! You have successfully built and executed an API call for ACLED’s API! You are encouraged to visit the endpoint sections on this website (see links at the top of this section). There you will find walkthroughs, details, and examples of different tools for every endpoint in ACLED’s API.

Best of luck! 🚀