GDELT Cloud Documentation - Global News Event Analytics API

Overview

get_cameoplus_events_summary returns aggregated totals and bucketed counts for AI-coded CAMEO+ events. It is the broad-and-shallow counterpart to get_cameoplus_events — designed to understand domain activity, geographic distribution, and average event intensity before fetching individual records. Results include a totals object (aggregate across the entire filter) and a buckets array (one row per group_by dimension). Each bucket includes avg/max magnitude, market_sensitivity, systemic_importance, and propagation_potential in addition to event counts.

Progressive Disclosure Pattern

1. get_cameoplus_events_summary(days=7, group_by='domain')
   → Which domains are most active this week?

2. get_cameoplus_events_summary(domain='ECONOMIC', days=7, group_by='country')
   → Where are economic events happening?

3. get_cameoplus_events(domain='ECONOMIC', country='USA')
   → Individual economic events in the US

Parameters

Parameter	Type	Default	Description
`group_by`	enum	`domain`	Dimension to group results by. See values below.
`days`	integer	`7`	Lookback window in days from `date`. Max 90.
`date`	string	today UTC	Anchor/end date in `YYYY-MM-DD` format.
`domain`	enum	—	Filter to a specific CAMEO+ domain. See domain values below.
`event_code`	string	—	Filter by event code or domain prefix. Supports exact match (`'EC02'`) or prefix match (`'EC'` = all ECONOMIC codes). See full code table below.
`country`	string	—	ISO-3 country code (e.g. `'USA'`, `'DEU'`, `'CHN'`). Must be a 3-letter code — full names will not match.
`region`	enum	—	Geographic region. Expands to the corresponding ISO-3 country list. Only one region per request. See valid values below.
`admin1`	string	—	First-level administrative division as stored in GDELT. Must be used with `country`. Use the full official name. Examples: `'California'` (USA), `'Bavaria'` (Germany), `'São Paulo'` (Brazil), `'Guangdong'` (China), `'Île-de-France'` (France).
`magnitude_min`	number	—	Minimum magnitude score (0–10). Pre-filters events before aggregation.
`magnitude_max`	number	—	Maximum magnitude score (0–10).
`systemic_min`	number	—	Minimum systemic importance score (0–1).
`market_min`	number	—	Minimum market sensitivity score (0–1).

`group_by` Values

Value	Description
`domain`	One bucket per CAMEO+ domain (default). Shows which domains are most active.
`date`	One bucket per day, ascending. Use for trend lines over time.
`country`	One bucket per country. Includes centroid lat/lon for map rendering.
`event_code`	One bucket per specific event code. Most useful combined with a `domain` filter.

`region` Values

Western Africa, Middle East, Eastern Africa, Southern Asia, East Asia, Eastern Europe, Latin America & Caribbean, South-Eastern Asia, Northern America, Western Europe, Central Asia, Oceania, Middle Africa, Northern Africa, Southern Africa, Caribbean, Central America

`domain` Values

Value	Description
`POLITICAL`	Diplomatic, cooperative, and non-violent coercive political events (CAMEO 01–17)
`ECONOMIC`	Macroeconomic indicators, monetary policy, fiscal policy, trade, market stress
`CORPORATE`	M&A, bankruptcies, production capacity, technology milestones, capital allocation
`TECHNOLOGY`	AI capability, military technology, cyber operations, space, strategic tech controls
`INFRASTRUCTURE`	Energy, transport, supply chain, communications infrastructure disruptions
`ENVIRONMENT`	Geophysical hazards, meteorological events, climate events, pollution
`HEALTH`	Disease outbreaks, pandemics, vaccines, health policy, health system crises
`DEMOGRAPHIC`	Refugee flows, migration, population crises, labor events
`INFORMATION`	Disinformation campaigns, information controls, major leaks, narrative warfare

`event_code` Values

ECONOMIC (EC__)

Code	Event
`EC01`	Macroeconomic Indicator Release
`EC02`	Monetary Policy Action
`EC03`	Fiscal Policy Action
`EC04`	Trade Policy Action
`EC05`	Market Stress Event
`EC06`	Currency Event
`EC07`	Sovereign Debt Event

Use 'EC' as a prefix to match all 7 ECONOMIC codes.

CORPORATE (CO__)

Code	Event
`CO01`	Merger or Acquisition
`CO02`	Bankruptcy or Restructuring
`CO03`	Production Capacity Change
`CO04`	Technology Development Milestone
`CO05`	Capital Allocation Event
`CO06`	Regulatory or Legal Action
`CO07`	Leadership or Governance Change
`CO08`	Supply Chain Shock

TECHNOLOGY (TE__)

Code	Event
`TE01`	AI Capability Event
`TE02`	Military Technology Event
`TE03`	Cyber Event
`TE04`	Space or Satellite Event
`TE05`	Strategic Technology Control
`TE06`	Critical Tech Infrastructure

INFRASTRUCTURE (IN__)

Code	Event
`IN01`	Energy Infrastructure Event
`IN02`	Transport Disruption
`IN03`	Supply Chain Disruption
`IN04`	Communications Infrastructure
`IN05`	Deliberate Infrastructure Sabotage
`IN06`	Water Infrastructure Event

ENVIRONMENT (EN__)

Code	Event
`EN01`	Geophysical Hazard
`EN02`	Meteorological Hazard
`EN03`	Climate Event
`EN04`	Environmental Pollution Event
`EN05`	Environmental Policy or Agreement

HEALTH (HE__)

Code	Event
`HE01`	Disease Outbreak
`HE02`	Pandemic or Global Health Emergency
`HE03`	Vaccine or Treatment Milestone
`HE04`	Public Health Policy Action
`HE05`	Health System Crisis

DEMOGRAPHIC (DE__)

Code	Event
`DE01`	Mass Displacement or Refugee Event
`DE02`	Migration Event
`DE03`	Population Crisis
`DE04`	Labor Event
`DE05`	Urbanization or Housing Event

INFORMATION (IF__)

Code	Event
`IF01`	Disinformation or Influence Operation
`IF02`	Information Control Action
`IF03`	Major Leak or Disclosure
`IF04`	Narrative Warfare Event

POLITICAL (01–17)

Uses standard CAMEO 2-digit codes for diplomatic/political interactions. Examples: 01 Public statement, 04 Consult, 05 Diplomatic cooperation, 13 Threaten, 14 Protest/Demand, 17 Coerce. Use '01'–'17' for exact match or no prefix for domain-level.

Data Structure

{
  "success": true,
  "group_by": "domain",
  "totals": {
    "event_count": 1842,
    "avg_magnitude": 5.3,
    "max_magnitude": 9.8,
    "avg_market_sensitivity": 0.54,
    "max_market_sensitivity": 0.97,
    "avg_systemic_importance": 0.61,
    "max_systemic_importance": 0.99,
    "avg_propagation_potential": 0.48,
    "avg_goldstein_scale": -1.2,   // non-null only when POLITICAL events in scope
    "avg_confidence": 0.87,
    "countries_affected": 89,
    "domains_active": 9,
    "centroid_lat": null,   // only present when country/region filter active
    "centroid_lon": null
  },
  "buckets": [
    {
      "domain": "ECONOMIC",
      "event_count": 412,
      "avg_magnitude": 5.8,
      "max_magnitude": 8.9,
      "avg_market_sensitivity": 0.71,
      "max_market_sensitivity": 0.97,
      "avg_systemic_importance": 0.68,
      "max_systemic_importance": 0.99,
      "avg_propagation_potential": 0.52,
      "avg_goldstein_scale": null,
      "avg_confidence": 0.89,
      "countries_in_bucket": 67,
      "domains_in_bucket": null   // omitted when group_by=domain
    }
  ],
  "filters": { "days": 7 },
  "metadata": { "bucket_count": 9, "execution_time_ms": 38 }
}

Latent Attribute Averages

Each bucket includes average and max values for the four CAMEO+ latent attributes:

Attribute	Range	Description
`avg_magnitude` / `max_magnitude`	0–10	Domain-specific intensity. Routine = 3–4, major structural events = 8–10.
`avg_market_sensitivity` / `max_market_sensitivity`	0–1	Expected financial market impact. Rate decisions, tariffs score high.
`avg_systemic_importance` / `max_systemic_importance`	0–1	How broadly the event affects systems/institutions.
`avg_propagation_potential`	0–1	Likelihood of cascading or contagion effects.
`avg_goldstein_scale`	-10 to +10	Only non-null when bucket contains POLITICAL-domain events.

Caching

Historical queries (date before today UTC): cached 24 hours
Live queries (includes today): cached until 7 minutes past the next UTC hour

Example Queries

get_cameoplus_events_summary(
    days=7,
    group_by="domain"
)
# → Which CAMEO+ domains are most active this week?

Common Use Cases

“Which domains are most active this week?” → days=7, group_by='domain'
“Show me a daily trend of economic events” → domain='ECONOMIC', days=30, group_by='date'
“Which countries have the most market-sensitive events?” → market_min=0.7, days=7, group_by='country'
“What’s the average magnitude of tech events in East Asia?” → domain='TECHNOLOGY', region='East Asia', days=30, group_by='domain'
“Break down economic events by specific code” → domain='ECONOMIC', days=30, group_by='event_code'
“Show me high-systemic-importance events in Europe” → region='Western Europe', systemic_min=0.8, days=7, group_by='country'

get_cameoplus_events

Individual CAMEO+ event records — the drill-down step after this summary

get_conflict_events_summary

Aggregate summary for ACLED conflict events

get_media_events

News story clusters that source CAMEO+ events via cluster_id

Overview

Tools

Resources

Prompts

Integrations

get_cameoplus_events_summary

Overview

Progressive Disclosure Pattern

Parameters

`group_by` Values

`region` Values

`domain` Values

`event_code` Values

Data Structure

Latent Attribute Averages

Caching

Example Queries

Common Use Cases

get_cameoplus_events

get_conflict_events_summary

get_media_events

Overview

Tools

Resources

Prompts

Integrations

​Overview

​Progressive Disclosure Pattern

​Parameters

​group_by Values

​region Values

​domain Values

​event_code Values

​Data Structure

​Latent Attribute Averages

​Caching

​Example Queries

​Common Use Cases

​Related Tools

get_cameoplus_events

get_conflict_events_summary

get_media_events

Overview

Progressive Disclosure Pattern

Parameters

`group_by` Values

`region` Values

`domain` Values

`event_code` Values

Data Structure

Latent Attribute Averages

Caching

Example Queries

Common Use Cases

Related Tools