API
Access generated GDELT Cloud Events, clustered Stories, linked Entities, 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, 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 turns global news flow into structured Events, Stories, Entities, summaries, and geographic context — plus Energy Data asset registries from Global Energy Monitor — that software can query directly through REST APIs and Agent/MCP workflows.
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.