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 turns global news flow into structured Events, Stories, Entities, Situations, summaries, and country 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.