Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

GDELT Cloud generates structured Event records from clustered Stories. Public API v2 exposes two Event families:
FamilyMeaning
conflictConflict, political violence, protests, riots, and strategic developments.
cameoplusPolitical and structural Events across public CAMEO+ domains.
Every public Event links back to Story evidence where available and is shaped for analyst workflows: normalized geography, actors, categories, metrics, linked Stories, linked Entities, and top articles.
GDELT Cloud independently generates its Conflict Event records from GDELT Cloud Story clusters. We follow ACLED-style methodology where useful, but do not use, license, or redistribute ACLED’s proprietary dataset.

​
Conflict Events

Conflict Events cover:
  • battles
  • explosions and remote violence
  • violence against civilians
  • protests
  • riots
  • strategic developments
Typical fields include:
  • category and subcategory
  • actors
  • geo.country, geo.region, geo.continent, geo.admin1, geo.location, geo.latitude, geo.longitude
  • metrics.significance
  • metrics.goldstein_scale
  • has_fatalities and fatalities
  • story_refs, entity_refs, and top_articles
Use has_fatalities=true for fatality monitoring. v2 intentionally does not expose fatality min/max filters.

​
CAMEO+ Events

CAMEO+ is the GDELT Cloud generated event layer for political and structural developments outside the Conflict family. Public v2 domains:
DomainCovers
POLITICALCAMEO-style diplomatic, cooperative, verbal conflict, and non-violent coercive actions.
ECONOMICMacro, monetary, fiscal, trade, market stress, currency, and sovereign debt events.
CORPORATEM&A, bankruptcy, production capacity, capital allocation, legal/regulatory, leadership, and supply-chain shocks.
TECHNOLOGYAI, cyber, strategic technology controls, space, military technology, and critical tech infrastructure.
INFRASTRUCTUREEnergy, transport, supply chain, communications, sabotage, and water infrastructure.
HEALTHOutbreaks, public health emergencies, vaccines/treatments, policy actions, and health-system stress.
INFORMATIONDisinformation, information control, major leaks, and narrative warfare.
ENVIRONMENTGeophysical hazards, meteorological hazards, climate events, pollution, and environmental policy.
CAMEO+ metrics can include:
  • magnitude
  • systemic_importance
  • propagation_potential
  • market_sensitivity
  • goldstein_scale for POLITICAL Events where meaningful

​
Goldstein Scale

metrics.goldstein_scale is public and important:
  • present for all Conflict Events
  • present for CAMEO+ POLITICAL Events where meaningful
  • null for non-political CAMEO+ domains
It ranges from cooperative to conflictual:
RangeMeaning
+5 to +10Cooperative, conciliatory, or de-escalatory action.
-4 to +4Neutral, mixed, low-intensity, or context-dependent action.
-5 to -10Conflictual, coercive, violent, or severe action.

​
Ranking

v2 uses one canonical significance score for Events and Stories. Event significance combines factors such as Goldstein severity where meaningful, CAMEO+ metrics, fatalities for Conflict Events, article evidence volume, and confidence. Story significance combines linked Event significance, article count with caps to prevent noisy volume dominance, and recency. Default sort is sort=significance; use sort=recent when freshness matters most. Event and Story list/summary endpoints default to confidence_profile=precise, which keeps analyst-ready records and avoids obvious Story-family duplicates. Use confidence_profile=loose only when you need exhaustive/raw retrieval; Event list and summary endpoints also accept min_confidence=0..1 as a custom confidence floor.

​
Access

Use API v2 for new integrations: 
GET /api/v2/events
GET /api/v2/events/{event_id}
GET /api/v2/events/summary
GET /api/v2/stories
GET /api/v2/stories/{story_id}
GET /api/v2/stories/{story_id}/articles
For MCP agents, use Progressive Discovery: 
{
  "tool_name": "search_events",
  "tool_arguments": {
    "event_family": "cameoplus",
    "domain": "INFRASTRUCTURE",
    "country": "United States",
    "days": 14,
    "sort": "significance"
  }
}
v1 REST endpoints remain supported for existing direct API users, but v2 is the recommended public interface.