Unrest Service

Social unrest and protest event aggregation from ACLED and GDELT

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)

Show event object

event_id · string

Unique event identifier

event_date · string

Event date (ISO 8601)

event_type · string

Type: protest, riot, violence_against_civilians, demonstration, strike

country · string

ISO-3166 alpha-2 country code

location · string

City or location name

latitude · number

Event latitude

longitude · number

Event longitude

actor1 · string

Primary actor/group involved

notes · string

Event description and context

fatalities · number

Reported fatalities (if available)

participants · number

Estimated participant count (if available)

source · string

Data source: ACLED, GDELT, or ACLED+GDELT (deduplicated)

source_scale · number

GDELT GoldsteinScale (-10 to +10, negative = conflict)

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

Type	Description	Examples
protest	Peaceful demonstrations	Marches, rallies, sit-ins
riot	Violent disorder	Property damage, clashes with police
violence_against_civilians	Targeted violence	Attacks on protesters, police brutality
demonstration	General demonstration	Multi-issue protests, symbolic actions
strike	Labor actions	Work stoppages, walkouts

Use Cases

Stability monitoring

Track protest activity and civil unrest for geopolitical risk assessment and Country Instability Index (CII) scoring.

Event forecasting

Identify emerging protest movements before they escalate, based on frequency and participant trends.

Supply chain risk

Monitor unrest near ports, manufacturing hubs, and logistics corridors for business continuity planning.

Media analysis

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.