Skip to main content
The UnrestService provides aggregated social unrest data including protests, riots, and civil disorder events from dual sources (ACLED and GDELT) with Haversine-based deduplication.

​
Base Path

/api/unrest/v1

​
Endpoints

​
ListUnrestEvents

Retrieves protest, riot, and civil unrest events from ACLED and GDELT with geographic and temporal filtering. HTTP Method: GET Path: /api/unrest/v1/list-unrest-events

​
Request Parameters

​
days
number
default:"7"
Time window in days (1-30)
​
country
string
ISO-3166 alpha-2 country code filter (e.g., US, FR, CN)
​
region
string
Geographic region filter: americas, europe, asia, africa, mena, oceania
​
event_type
string
Event type filter: protest, riot, violence, strike, demonstration
​
min_participants
number
Minimum estimated participant count

​
Response Fields

​
events
array
Array of unrest events (deduplicated across ACLED and GDELT sources)
​
total_count
number
Total events after deduplication
​
dedup_removed
number
Number of duplicate events removed via Haversine matching

​
Example Request

curl "https://worldmonitor.app/api/unrest/v1/list-unrest-events?days=7&region=europe&event_type=protest"

​
Example Response

{
  "events": [
    {
      "event_id": "ACLED-2024-03-001",
      "event_date": "2024-03-01T14:00:00Z",
      "event_type": "protest",
      "country": "FR",
      "location": "Paris",
      "latitude": 48.8566,
      "longitude": 2.3522,
      "actor1": "Labor unions",
      "notes": "Protest against pension reform legislation",
      "fatalities": 0,
      "participants": 50000,
      "source": "ACLED",
      "source_scale": null
    }
  ],
  "total_count": 1,
  "dedup_removed": 3
}

​
Deduplication Logic

Unrest events from ACLED and GDELT are deduplicated using:
  1. Haversine distance: Events within 5km of each other
  2. Temporal proximity: Events within 24 hours
  3. Event type matching: Same protest/riot classification
When duplicates are found, ACLED is preferred as the canonical source due to higher data quality and human verification.

​
Event Type Taxonomy

TypeDescriptionExamples
protestPeaceful demonstrationsMarches, rallies, sit-ins
riotViolent disorderProperty damage, clashes with police
violence_against_civiliansTargeted violenceAttacks on protesters, police brutality
demonstrationGeneral demonstrationMulti-issue protests, symbolic actions
strikeLabor actionsWork stoppages, walkouts

​
Use Cases

Track protest activity and civil unrest for geopolitical risk assessment and Country Instability Index (CII) scoring.
Identify emerging protest movements before they escalate, based on frequency and participant trends.
Monitor unrest near ports, manufacturing hubs, and logistics corridors for business continuity planning.
Correlate protest events with news coverage to detect under-reported or suppressed demonstrations.

​
Data Sources

  • ACLED: Armed Conflict Location & Event Data Project (human-verified, researcher-curated)
  • GDELT: Global Database of Events, Language, and Tone (machine-coded, near-real-time)
ACLED data requires a researcher account. See API Keys for setup.
GDELT provides faster coverage but ACLED offers higher accuracy. Dual-source aggregation balances speed and quality.

Build docs developers (and LLMs) love

Get started for freeTalk to us