CAST endpoint
Learn how to use the CAST endpoint
20 May 2025Last updated: 30 September 2025
In March 2023, ACLED released the Conflict Alert System (CAST), a conflict prediction tool. CAST provides a monthly forecast of the number of political violence events for every country and territory in the world up to six months in advance.
Access to the CAST endpoint
To access the CAST API endpoint, you must make a call to:https://acleddata.com/api/cast/
To authenticate, follow the instructions in ourGetting started guide.
As is the case when using any ACLED data, your usage of the CAST tool must follow ACLED’s Terms of Use & Attribution Policy. For instance, if for non-commercial purposes you want to reproduce or republish a visual, graphic, or map from ACLED CAST (rather than creating an original image using raw data), you should include the following citation:
ACLED. (DD MM YYYY). “ACLED Conflict Alert System.” Armed Conflict Location & Event Data Project (ACLED). https://acleddata.com/early-warning-research-hub/conflict-alert-system/ © 2023 ACLED All rights reserved. Used with permission from ACLED. Accessed (DD MM YYYY).
Query filters
After gaining access to the CAST endpoint, you can request data in the same way as you would for other endpoints in ACLED’s API. For instance, you can use query filters to limit your request so that your API call returns only the data you need. Basic instructions for using query filters are included below, but you can find a step-by-step set of directions in the Get started section and Advanced concepts section. You can find a list of query filters that can be used in the CAST endpoint in the following table:
Query Name | Type | Query String |
country | LIKE | ?country={text} |
admin1 | LIKE | ?admin1={text} |
month | LIKE | ?month={text} |
year | = | ?year={yyyy} |
total_forecast | = | ?total_forecast={text} |
battles_forecast | = | ?battles_forecast={text} |
erv_forecast | = | ?erv_forecast={text} |
vac_forecast | = | ?vac_forecast={text} |
total_observed | = | ?total_observed={text} |
battles_observed | = | ?battles_observed={text} |
erv_observed | = | ?erv_observed={text} |
vac_observed | = | ?vac_observed={text} |
timestamp | >= | ?timestamp={unix timestamp} |
As is the case with other endpoints, query types can be modified to fit your needs. To modify the query type, you should add an extra command with the name of the query filter you want to change and the suffix _where, followed by the desired query type (e.g. year_where=> if you want to use the query type “greater than”). You can visit the Advanced concepts section for a more detailed explanation and list of query type options.
Remember that you can also combine multiple query filters and query types, either by using &’,|, or:OR:` depending on your needs. Please see the Advanced concepts section for more information.
Note: You can convert a date to a Unix timestamp using any online timestamp calculator, such as the one linked here.
Returned data
When you execute your API call, you will receive data containing the following variables:
Attribute Name | Type | Description |
country | string | The name of the country |
admin1 | string | The name of the first-level administrative division |
month | string | The month of events |
year | int | The year of events |
total_forecast | int | Total number of events forcasted |
battles_forecast | int | Total number of battles events forecasted |
erv_forecast | int | Total number of explosions/remote violence events forecasted |
vac_forecast | int | Total number of violence against civilians events forecasted |
total_observed | int | Total number of events observed. This column will be populated once the given month has passed |
battles_observed | int | Total number of battles events observed. This column will be populated once the given month has passed |
erv_observed | int | Total number of explosions/remote violence events observed. This column will be populated once the given month has passed |
vac_observed | int | Total number of violence against civilians events observed. This column will be populated once the given month has passed |
timestamp | int or date | The unix timestamp (or date stamp) this data entry was last updated |
Note: You can learn more about the data in each of these columns in the CAST methodology guide
To reduce the size of the returned file and streamline later analyses, you can limit which columns are returned by using the fields filter to specify which columns you want to receive. If you would like to request multiple columns, list them all while separating each column name by the pipe operator (|). For instance, if you are only interested in the admin1, month, vac_forecast and battles_forecast columns, you can include the following section in your URL:
…&fields=admin1|month|battles_forecast|vac_forecast
Returned data - JSON only.
If you request your data in .json format (the default option) rather than .csv, .txt, or .xml, you will also receive the following as part of the API response:
Attribute Name | Type | Description |
status | int | A number representing the request status |
success | boolean | A boolean representation on the success of the call |
last_update | int | The number of hours since the last update to the data |
count | int | The number of data rows returned |
messages | array | An array of information messages that may require future action |
data | array | The rows of data returned. For details of attributes returned in each row, see the section above |
filename | string | The filename that will be used for .csv calls |
data_query_restrictions | obj | Details of any restrictions applied to your query, including countries, event types, regions, data history, data recency |
Example - URL 💻
You can now apply what you learned above to a simple example: gathering forecast data for “Argentina” and “Brazil” in 2023.
You can build your query by following these steps:
- Begin with the ACLED API’s base URL.
https://acleddata.com/api/
- Add the CAST endpoint.
https://acleddata.com/api/cast/
- Specify the desired response format.
https://acleddata.com/api/cast/read.csv
- Add query filters specifying the desired countries.
https://acleddata.com/api/cast/read?_format=csv&country=Brazil|Argentina
- Add a query filter specifying the desired year.
https://acleddata.com/api/cast/read?_format=csv&country=Brazil|Argentina&year=2023
Now that your URL is built, you can paste it into your internet browser to receive your requested data from ACLED’s server. Your file should look something like this:
country | admin1 | month | year | total_forecast | battles_forecast | erv_forecast | vac_forecast | total_observed | battles_observed | erv_observed | vac_observed | timestamp |
Argentina | Salta | March | 2023 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1704898526 |
Brazil | Parana | October | 2023 | 8 | 3 | 1 | 4 | 9 | 2 | 0 | 7 | 1704898532 |
Argentina | Santa Fe | August | 2023 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1704898526 |
Brazil | Mato Grosso do Sul | December | 2023 | 12 | 6 | 0 | 6 | 22 | 14 | 0 | 8 | 1704898532 |
Brazil | Distrito Federal | September | 2023 | 3 | 1 | 0 | 2 | 0 | 0 | 0 | 0 | 1704898532 |
Brazil | Ceara | July | 2023 | 6 | 2 | 0 | 4 | 6 | 2 | 0 | 4 | 1704898532 |
Argentina | Rio Negro | September | 2023 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1704898526 |
Brazil | Roraima | March | 2023 | 9 | 4 | 0 | 5 | 2 | 1 | 0 | 1 | 1704898533 |
Argentina | Chubut | December | 2023 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1704898525 |
Brazil | Sergipe | November | 2023 | 6 | 3 | 0 | 3 | 5 | 5 | 0 | 0 | 1704898533 |
Success! Your file contained data for “Argentina” and “Brazil” in 2023!
Best of luck building your next URL! 🚀
