GDELT Cloud Docs — Global Event Data API & MCP

What is Conflict Data?

GDELT Cloud’s Conflict Data feature provides generated structured records of political violence, armed conflict, protests, riots, and strategic developments derived from GDELT Cloud Story clusters. Events follow ACLED-style methodology and taxonomy, but are independently generated by GDELT Cloud. Events are generated automatically from the same Story clusters that power the GDELT Cloud Stories surface, giving you a structured, queryable conflict layer linked back to article evidence.

GDELT Cloud conflict data is modeled after the ACLED codebook and follows ACLED’s classification hierarchy, actor typing, and geographic coding conventions. GDELT Cloud independently generates its own conflict event records from GDELT Cloud Story clusters built from the upstream GDELT Project article stream — we do not use, license, or re-distribute ACLED’s proprietary dataset. The ACLED badge indicates we follow ACLED methodology and taxonomy, not that we source from ACLED.Learn more about the ACLED project at acleddata.com.

Beta: GDELT Cloud conflict event coding is in beta. Classification accuracy, coverage, and field definitions will improve over time.

Event Structure

Each conflict event follows the 3-level ACLED classification hierarchy:

disorder_type           (top level)
  └── event_type        (mid level)
        └── sub_event_type  (most specific)

Disorder Types

Disorder Type	Covers
Political violence	Armed conflict, attacks, explosions, targeted violence
Demonstrations	Protests, riots, mob violence
Strategic developments	Agreements, arrests, territorial changes, base establishment

There is no disorder_type query parameter. These are broader groups, not individual category values. To query Political violence, use category=Battles,Explosions/Remote violence,Violence against civilians: comma-separated categories are an OR filter. Keep the same geographic and time filters. See the equivalent category filters for each broader group.

Event Types & Sub-types

Battles

Armed combat between organized groups.

Armed clash — mutual exchange of fire; neither side clearly won/lost territory
Government regains territory — state forces retake area from non-state actors (confirmed control change)
Non-state actor overtakes territory — armed group captures territory (confirmed control change)

Explosions / Remote violence

Attacks using weapons that allow distance between attacker and target.

Air/drone strike — aerial bombardment by aircraft or drone
Shelling/artillery/missile attack — indirect fire (artillery, rockets, mortars, missiles)
Remote explosive/landmine/IED — planted device detonates; attacker not present
Suicide bomb — attacker intends to die in the blast
Grenade — grenade thrown or launched
Chemical weapon — chemical agents used

Violence against civilians

Deliberate violence by armed actors targeting unarmed non-combatants.

Attack — lethal violence or targeted assassination
Abduction/forced disappearance — non-lethal taking or detention
Sexual violence — sexual violence by armed actors against civilians

Protests

Organized demonstrations.

Peaceful protest — no violence by protesters or security forces
Protest with intervention — security forces use non-lethal crowd control
Excessive force against protesters — security forces use lethal force

Riots

Collective violence, often spontaneous.

Violent demonstration — protesters initiate violence (arson, projectiles, property destruction)
Mob violence — spontaneous communal clashes between civilian groups

Strategic developments

Concrete actions that change the conflict landscape.

Agreement — signed ceasefire, peace deal, or diplomatic accord
Arrests — named political or military figure arrested
Headquarters or base established — military base formally established or force deployed
Looting/property destruction — confirmed looting event
Non-violent transfer of territory — formal handover without combat
Change to group/activity — confirmed change in armed group structure/activity
Disrupted weapons use — weapons cache confirmed seized or interdicted
Other

Actor Coding

Each event records up to two actors using the ACLED actor typing system — a state actor, a rebel group, a militia, rioters, protesters, civilians, or an external force. The eight values, in code order, are published in the value reference. inter1 is the acting side and inter2 the receiving side. None is a legal value for inter2 alone, in a one-sided event where there is no second actor — it is a real classification, not a missing field. The interaction field encodes the actor pair as a normalized label: 'State forces–Rebel groups', 'State forces–Civilians', 'Protesters only', etc.

Geographic Coding

Each event is located at up to 4 levels of precision:

country — full English country name (e.g. Ukraine, Gaza Strip)
admin1 — state or province (e.g. Donetsk Oblast, Khartoum)
admin2 / admin3 — district and sub-district (when available)
location — named place (city, town, military base)
latitude / longitude — decimal coordinates (when available)

geo_precision says how exactly the event was located, and it matters more than it looks: it is the difference between an event at an asset and an event somewhere in the same country. The scale and the companion geo_precision_label values are in the value reference.

Data Quality

Field	Notes
fatalities	Best-supported most likely figure from the sources (not automatically the lowest). Disputes noted in `notes`.
civilian_targeting	Only `true` when civilians are the primary target, not incidental collateral harm.
confidence	AI coding confidence 0–1. Lower values indicate ambiguous or indirect sources.
time_precision	How exactly the event was dated — see the value reference. A coarse value on a daily series is a month-wide event pinned to one bucket, not a same-day observation.

Accessing Conflict Data

In the app

The API Arena runs real calls against the same serve functions this reference documents, so a request you build there is one you can copy into curl unchanged.

REST API

Without explicit dates, Event lists use the last 24 hours, or 30 days when filtering by entity. Read meta.query_window for the effective bounds. Narrow with developer-facing filters such as event-type category values, sub-event-type subcategory values, civilian_targeting=true, country/region/continent filters, date windows up to 30 days, sort, and pagination. The legacy event_family=conflict filter is still accepted for existing clients, but new integrations should use category=Battles, category=Protests, and the other Conflict event types directly.

curl "https://gdeltcloud.com/api/v2/events?category=Battles&subcategory=Armed%20clash&country=Ukraine&days=7&sort=significance" \
  -H "Authorization: Bearer gdelt_sk_..."

curl "https://gdeltcloud.com/api/v2/events?category=Explosions%2FRemote%20violence&subcategory=Air%2Fdrone%20strike&days=7" \
  -H "Authorization: Bearer gdelt_sk_..."

curl "https://gdeltcloud.com/api/v2/events?category=Violence%20against%20civilians&civilian_targeting=true&days=7" \
  -H "Authorization: Bearer gdelt_sk_..."

curl "https://gdeltcloud.com/api/v2/events?category=Explosions%2FRemote%20violence&subcategory=Air%2Fdrone%20strike&search=airstrikes%20civilian%20infrastructure&days=7" \
  -H "Authorization: Bearer gdelt_sk_..."

curl "https://gdeltcloud.com/api/v2/events?category=Battles&subcategory=Armed%20clash&search=rebel%20armed%20clash%20territory&country=Sudan&days=30" \
  -H "Authorization: Bearer gdelt_sk_..."

Semantic Search

The v2 search parameter accepts natural-language queries and ranks results by semantic similarity when embeddings are available.

Semantic search is composable with every structured filter in the parameter reference, including geography, taxonomy, fatality and date-window filters.

Example queries that work well:

Query	What it finds
`"airstrikes civilian infrastructure"`	Air/drone strikes on homes, utilities, hospitals
`"protest government crackdown"`	Demonstrations with security force intervention
`"rebel advance territorial control"`	Non-state actors seizing or holding territory
`"military offensive shelling artillery"`	Artillery and missile attacks in active fronts
`"ceasefire agreement peace deal"`	Strategic developments / agreements
`"kidnapping abduction forced disappearance"`	Violence against civilians — abductions

When to use search vs structured filters:

Use structured filters when you know the taxonomy value — see the parameter reference
Use search when describing a situation in plain language, or when the precise sub-type is uncertain
Combine both: search=artillery shelling front line&country=Ukraine narrows geography while ranking semantically

MCP Tool

For AI agents, use Progressive Discovery and call search_events:

gdelt_cloud_tool_call(
  tool_name="search_events",
  tool_arguments={"country": "Sudan", "category": "Battles", "subcategory": "Armed clash", "days": 7}
)

See the GDELT Cloud v2 MCP tools for full parameter documentation.

API v2

Clean Events, Stories, summaries, Entities, and geo discovery

GDELT Cloud v2 MCP Tools

Progressive Discovery tool reference for AI agent access

ACLED Data Project

Learn about the ACLED methodology and original dataset

Start here

Use cases

Monitors

Products

Data

How the data is made

Conflict Data

What is Conflict Data?

Event Structure

Disorder Types

Event Types & Sub-types

Actor Coding

Geographic Coding

Data Quality

Accessing Conflict Data

In the app

REST API

Semantic Search

MCP Tool

API v2

GDELT Cloud v2 MCP Tools

ACLED Data Project

​What is Conflict Data?

​Event Structure

​Disorder Types

​Event Types & Sub-types

​Actor Coding

​Geographic Coding

​Data Quality

​Accessing Conflict Data

​In the app

​REST API

​Semantic Search

​MCP Tool

​Related Resources

API v2

GDELT Cloud v2 MCP Tools

ACLED Data Project

What is Conflict Data?

Event Structure

Disorder Types

Event Types & Sub-types

Actor Coding

Geographic Coding

Data Quality

Accessing Conflict Data

In the app

REST API

Semantic Search

MCP Tool

Related Resources