Skip to main content

​
What Makes GDELT Cloud Different

GDELT Cloud transforms the global news stream into structured intelligence:
  • Media Events — AI-clustered news stories with resolved sentiment, event coding, and entity extraction
  • Conflict Events — ACLED-style conflict records (battles, airstrikes, protests) AI-coded from news clusters
  • CAMEO+ Events — AI-coded non-conflict events across 9 domains with magnitude, market sensitivity, and systemic importance scores
  • Entity Graph (GEG) — Wikipedia-verified entities with sentiment, salience, and co-occurrence networks
GDELT signals diplomatic and political moves 12–24h before traditional media, and surfaces non-obvious patterns across thousands of sources simultaneously.

​
Country Code Reference (Critical)

EndpointParamFormatExamples
/api/v1/media-eventsactor_countryISO-3USA, CHN, GBR, RUS
/api/v1/media-eventslocationFIPS 2-letterUS, CH, UK, RS, GM
/api/v1/conflict-eventscountryFull English nameUkraine, Sudan, Iran
/api/v1/cameoplus-eventscountryISO-3UKR, SDN, IRN
/api/v1/entity-geg—Entity nameFull name, any case
Common mismatches: CH = China (not Switzerland), South Korea FIPS = KS not KR, UK ≠ GBR.

​
Workflow: Scan → Zoom → Enrich

​
Step 1 — Scan

# Top stories today
GET /api/v1/media-events
  ?days=1
  &detail=summary
  &limit=10

# Topic-focused
GET /api/v1/media-events
  ?search={YOUR_TOPIC}
  &days=7
  &detail=summary
  &limit=10

# Country/actor-focused
GET /api/v1/media-events
  ?actor_country={ISO3}
  &location={FIPS}
  &days=7
  &detail=summary

​
Step 2 — Zoom

# Drill into a story
GET /api/v1/media-events/cluster
  ?cluster_id={ID}
  &days=7
  &detail=summary

# Drill into an entity
GET /api/v1/entity-geg
  ?entity={NAME}
  &limit=10

​
Step 3 — Enrich

# Conflict context
GET /api/v1/conflict-events
  ?country={COUNTRY_NAME}
  &days=7
  &limit=20

# Non-conflict events
GET /api/v1/cameoplus-events
  ?country={ISO3}
  &domain=POLITICAL
  &days=7
  &limit=20

# Entity in GKG pipeline (fallback)
GET /api/v1/entity
  ?canonical_name={name}
  &type=person
  &days=7

​
Response Size Management

Endpointdetail=summarydetail=standarddetail=full
/media-events ×10~1,200 tok~5,000 tok~10,000 tok
/media-events/cluster~500 tok~1,500 tok~3,000+ tok
/entity-geg~300 tok~1,200 tok~1,500 tok
Always start with detail=summary and limit=5–10. Escalate only when needed.

​
Conflict Events Quick Reference

# Aggregate trends first
GET /api/v1/conflict-events/summary?country={COUNTRY}&days=30&group_by=date
GET /api/v1/conflict-events/summary?region={REGION}&days=14&group_by=country

# Then drill into events
GET /api/v1/conflict-events?country={COUNTRY}&event_type=Battles&days=7
GET /api/v1/conflict-events?country={COUNTRY}&event_type=Explosions/Remote violence&days=7
GET /api/v1/conflict-events?country={COUNTRY}&fatalities=true&days=7

​
CAMEO+ Events Quick Reference

# Aggregate first
GET /api/v1/cameoplus-events/summary?days=7&group_by=domain
GET /api/v1/cameoplus-events/summary?domain=ECONOMIC&days=30&group_by=date

# Then events
GET /api/v1/cameoplus-events?domain=POLITICAL&country={ISO3}&days=7
GET /api/v1/cameoplus-events?domain=CORPORATE&days=7&magnitude_min=6.0
GET /api/v1/cameoplus-events?search=central bank interest rate decision&days=7

​
Common Pitfalls

PitfallFix
Wrong country code formatCheck the reference table above for each endpoint
/entity-geg returns emptyTry /entity (GKG pipeline) as fallback
Response too largeUse detail=summary and limit=5-10
No city-level filterUse FIPS location + search with city name
No trend over timeRun same query at different date/days windows
Cluster data missingPass the same date and days from the discovery call