API
Access generated GDELT Cloud Events, clustered Stories, linked Entities, connected Situations, country context, publication activity, summaries, and geo discovery through a clean v2 REST API. v1 remains supported for existing direct API users.
Clean v2 endpoints for Events, Stories, summaries, Entities, Situations, country context, publication activity, admin1 discovery, and paginated Story articles.
Plain-English geography with ISO-3 and legacy FIPS accepted as aliases.
Canonical significance ranking plus recent sorting for dashboards, alerts, and reporting pipelines.
import os
import httpx
API_KEY = os.environ["GDELT_API_KEY"]
params = {
"country": "Lebanon",
"event_family": "conflict",
"has_fatalities": True,
"sort": "significance",
}
with httpx.Client(timeout=30) as client:
response = client.get(
"https://gdeltcloud.com/api/v2/events",
params=params,
headers={
"Authorization": f"Bearer {API_KEY}",
"Accept": "application/json",
},
)
response.raise_for_status()
events = response.json()["data"]API + MCP
Machine-readable world state for APIs and agents
GDELT Cloud connects Events, Stories, Entities and country context with Facilities, mineral statistics, energy registries and AI compute observations. Software and agents access the same documented data through REST and MCP, with source coverage and participant identities carried in the responses.
Clean REST API
Use standard HTTP clients to pull normalized global event objects into products, dashboards, and pipelines.
Entitlement-Based Access
API keys, rate limits, and usage tracking are tied to plans with API access.
Agent/MCP Native
Expose the same machine-readable state to Claude, Cursor, ChatGPT, LangGraph, and custom agents.
What geopolitical data can you query?
Search coded Events by place, actor, date, and category; follow their clustered Stories and source articles; resolve people, organizations, and places to linked Entity profiles. Country context and summaries help you turn those records into a monitored question or a repeatable research workflow.