v1
latestOpenAPI 3.0.32026-07-226744340.8 KBSummarize Events
Return dashboard-ready Event rollups by date, geography, category, or subcategory. Use group_by=subcategory under a parent category such as Battles to discover scoped sub-event buckets like Government regains territory, then reuse category+subcategory on /api/v2/events to fetch instances. Summaries use the same broad result coverage as Event lists and are designed for discovery before drilling into Events.
Query parameters
Summary grouping dimension. For Events, category is Conflict event type or CAMEO+ domain and subcategory is Conflict sub-event type or CAMEO+ event description/code. For Stories, category/subcategory grouping uses linked Event taxonomy; use story_category only as a Story-cluster filter.
Inclusive start date in YYYY-MM-DD, matched against the event or story date. Alias start_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.
Inclusive end date in YYYY-MM-DD, matched against the event or story date. Alias end_date is accepted for compatibility. Omit dates for the default recent window; explicit windows may not exceed 30 days.
Country filter, resolved through the shared resolveCountryInput layer so a plain English country name (United States), an ISO-2 code (US), an ISO-3 code (USA), or a common alias (UK, UAE, Czechia) all work interchangeably; output normalizes to the country name. Accepts a comma-separated list (any part unresolvable → 400 INVALID_COUNTRY), and can be combined with region/continent.
Plain English region such as Middle East, Western Africa, South Asia, or Europe. The backend expands this value to an ISO-3 country list; Events match location and actor-origin countries, while Stories match linked Event primary location.
Plain English continent such as Africa, Asia, Europe, North America, South America, or Oceania. The backend expands this value to an ISO-3 country list; Events match location and actor-origin countries, while Stories match linked Event primary location.
Optional state/province/admin1 location filter. Discover valid values through /api/v2/geo/admin1. Filters Event or Story location only, not actor origin.
Geographic bounding box on event latitude/longitude, formatted as lat_min,lon_min,lat_max,lon_max. Use for sub-country precision (e.g. a strait or port area). Combine with country or use alone; lat must be in [-90,90] and lon in [-180,180].
Deprecated legacy filter. Prefer category, which implies Conflict vs CAMEO+. Still accepted for backwards compatibility.
Stable linked Event product category. Use a Conflict event type such as Battles, Protests, or Explosions/Remote violence, or one CAMEO+ domain such as POLITICAL, INFRASTRUCTURE, or CRIME; values may be single or comma-separated. On Story endpoints this filters linked Event evidence. Use story_category only for legacy Story-cluster categories such as conflict_security. Full list: Taxonomy & Codes.
More specific linked Event subtype, CAMEO+ event description, or CAMEO+ code. Requires parent category and must belong to at least one selected category. For Conflict categories, use sub-event types such as Armed clash, Peaceful protest, or Air/drone strike. Validation errors include accepted_values, nearest_values when practical, and a corrected example. Full list: Taxonomy & Codes.
Deprecated legacy CAMEO+ domain enum. Prefer category/categories for new integrations; retained for backwards compatibility. Full list: Taxonomy & Codes.
Set true for fatality monitoring. v2 intentionally exposes only this boolean fatality filter.
Filter Conflict-linked evidence by ACLED civilian_targeting. true keeps records where civilians are the primary target; false excludes those records.
Significance minimum filter. Composite 0-1 Event significance score.
Significance maximum filter. Composite 0-1 Event significance score.
Confidence minimum filter. Model confidence for the structured Event record.
Confidence maximum filter. Model confidence for the structured Event record.
Goldstein scale minimum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful.
Goldstein scale maximum filter. Signed Goldstein scale. Applies to Conflict Events and CAMEO+ POLITICAL Events where meaningful.
Goldstein severity minimum filter. Absolute Goldstein intensity, regardless of positive or negative valence.
Goldstein severity maximum filter. Absolute Goldstein intensity, regardless of positive or negative valence.
Magnitude minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
Magnitude maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
Systemic importance minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
Systemic importance maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
Propagation potential minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
Propagation potential maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
Market sensitivity minimum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
Market sensitivity maximum filter. CAMEO+ detail metric. Only matches Events with CAMEO+ scores.
Filter to Events with at least one linked article in these source (origin) languages. Comma-separated ISO codes (en, zh, ar, …), OR'd; alias language accepted. Caveat: honored for every non-date group_by, and for a group_by=date query that also carries another qualifying filter — but IGNORED (and reported under applied_filters.ignored) on the lightweight group_by=date fast path with no other filter.
Number of summary buckets to return.
Response
Event summary buckets
Example response
{
"data": [
{
"metrics": {
"significance": {
"avg": 0.42,
"max": 0.91,
"min": 0.05
},
"goldstein_scale": {
"avg": -3.8,
"min": -8,
"max": 2,
"avg_severity": 4.2
},
"goldstein_severity": {
"avg": 4.2,
"min": 0.5,
"max": 8
},
"cameoplus": {
"magnitude": {
"avg": 6.1,
"min": 1.2,
"max": 9
},
"systemic_importance": {
"avg": 0.52,
"min": 0.11,
"max": 0.9
},
"propagation_potential": {
"avg": 0.47,
"min": 0.07,
"max": 0.81
},
"market_sensitivity": {
"avg": 0.31,
"min": 0.03,
"max": 0.75
}
},
"confidence": {
"avg": 0.83,
"min": 0.44,
"max": 0.98
},
"article_count": {
"total": 40,
"avg": 3.333,
"min": 1,
"max": 12
},
"fatalities": {
"events": 2,
"rate": 0.1667,
"total": 6
}
}
}
]
}