GDELT Cloud Docs — Global Event Data API & MCP

This page covers the conventions shared across every v2 endpoint. For the controlled vocabularies you pass as parameters, see Taxonomy & Codes; for copy-paste recipes, see the Cookbook.

Authentication

Every /api/v2/* request authenticates with a Bearer API key:

Authorization: Bearer gdelt_sk_...

Manage keys in the GDELT Cloud dashboard under Settings → API Keys. See Authentication for session vs. key auth and plan access.

Result coverage

Event, Story, and Entity list endpoints default to the exact past 24 hours while preserving broad discovery coverage, so you can find useful records before narrowing with structured filters. Confidence tuning is handled internally. Detail endpoints remain exhaustive by ID: GET /api/v2/events/{event_id} and GET /api/v2/stories/{story_id} resolve known records directly. Explicit date_start/date_end windows filter by event/story date and may not exceed 30 days.

Geography

Use plain-English country names in calls; ISO-3 and legacy FIPS aliases are accepted, but responses normalize country output to the plain-English name.

country=France
country=United States
country=South Korea

region and continent expand to ISO-3 country lists on the backend. Event queries match those countries against Event location plus actor-origin countries; Story queries use the same expansion through linked-Event location only. admin1 is optional and filters only the event/story location. The geo object is the primary event/story location. For Events, when a broad geo filter matches actor-origin geography instead, geo_context.actor_origin_countries shows why the record matched. For Stories, geo_context.actor_origin_countries is returned for context but does not drive the geo filter. See Taxonomy & Codes → Geography for the full continent and region enums.

Bounding box

Use bbox for sub-country filters such as straits, ports, basins, border zones, or any custom viewport. It is a comma-separated string in latitude-first order:

bbox=lat_min,lon_min,lat_max,lon_max

lat must be in [-90, 90] and lon in [-180, 180]. The filter applies to the Event’s primary geo.latitude/geo.longitude (and to linked-Event locations for Stories). Records without geocoded coordinates are excluded from bbox queries. bbox is supported on /api/v2/events, /api/v2/events/summary, /api/v2/stories, and /api/v2/stories/summary. /api/v2/energy/assets accepts the same lat-first bbox plus a separate near=lat,lon,radius_km proximity filter.

The preview Maritime endpoints use a longitude-first bbox (minLon,minLat,maxLon,maxLat) — the opposite axis order from Events/Stories/Energy. Watch the order when crossing surfaces.

Response objects

List endpoints return a success envelope with data and pagination; detail endpoints return a single data object; summary endpoints return group_by and grouped data buckets.

{
  "success": true,
  "data": [],
  "pagination": { "limit": 25, "cursor": null, "next_cursor": "25" }
}

Event card

Returned by GET /api/v2/events and GET /api/v2/events/{event_id}.

{
  "id": "conflict_20260417_example",
  "url": "https://gdeltcloud.com/story/example-story",
  "primary_story_url": "https://gdeltcloud.com/story/example-story",
  "family": "conflict",
  "title": "Example event title",
  "summary": "Short generated event summary.",
  "event_date": "2026-04-17",
  "category": "Protests",
  "subcategory": "Peaceful protest",
  "domain": "CONFLICT",
  "event_code": "ACLED-123",
  "geo": {
    "country": "France", "region": "Europe", "continent": "Europe",
    "admin1": "Ile-de-France", "location": "Paris",
    "latitude": 48.8566, "longitude": 2.3522
  },
  "geo_context": { "location_country": "France", "actor_origin_countries": ["France"] },
  "actors": [ { "name": "Protesters", "country": "France", "role": "actor1" } ],
  "metrics": {
    "significance": 0.72, "goldstein_scale": -2, "magnitude": null,
    "systemic_importance": null, "propagation_potential": null,
    "market_sensitivity": null, "confidence": 0.91, "article_count": 4
  },
  "has_fatalities": false, "fatalities": 0,
  "civilian_targeting": false, "civilian_targeting_label": null,
  "story_refs": [ { "id": "story_20260417_example", "url": "https://gdeltcloud.com/story/example-story", "title": "Example story", "story_date": "2026-04-17", "article_count": 4 } ],
  "entity_refs": [ { "id": "Paris", "name": "Paris", "type": "LOCATION", "wikipedia_url": "https://en.wikipedia.org/wiki/Paris" } ],
  "top_articles": [ { "url": "https://example.com/article", "title": "Example article", "rank": 1 } ]
}

Field	Description
`id`	Stable v2 Event identifier.
`url`, `primary_story_url`	Public GDELT Cloud Story URL for citation when the Event has a linked Story.
`family`	`conflict` or `cameoplus`.
`title`, `summary`	Generated Event headline and concise summary.
`event_date`	Event date in `YYYY-MM-DD`.
`category`, `subcategory`	Taxonomy fields. Conflict Events use event types (`Battles`, `Protests`, …) as `category` and sub-event types (`Armed clash`, `Peaceful protest`, …) as `subcategory`; CAMEO+ Events use domains as `category` and stable codes (`TE01`, `IN03`, …) as `subcategory`. Responses display canonical labels such as `TE01 · AI Capability Event`.
`domain`	CAMEO+ domain, or `CONFLICT` for Conflict Events.
`event_code`	Source event id, CAMEO+ event code, or null.
`geo`	Primary Event location.
`geo_context`	Explains broad-geography matches, especially actor-origin matches.
`actors`	Event actors with `name`, normalized `country`, and `role`.
`metrics`	Event significance and its generated metric inputs.
`has_fatalities`, `fatalities`	Fatality flag and count.
`civilian_targeting`, `civilian_targeting_label`	Conflict-only ACLED civilian-targeting flag and label.
`story_refs`	Linked Story references with public URLs.
`entity_refs`	Linked Entities with names, types, and Wikipedia URLs when available.
`top_articles`	Top 3 inline source articles. Use the Story articles endpoint for full lists.

Story card

Returned by GET /api/v2/stories and GET /api/v2/stories/{story_id}.

{
  "id": "story_20260417_example",
  "url": "https://gdeltcloud.com/story/example-story",
  "title": "Example story title",
  "story_date": "2026-04-17",
  "category": "infrastructure",
  "subcategory": null,
  "geo": {
    "country": "Japan", "region": "East Asia", "continent": "Asia",
    "admin1": "Tokyo", "location": "Tokyo", "latitude": 35.6762, "longitude": 139.6503
  },
  "geo_context": { "location_country": "Japan", "actor_origin_countries": ["Japan", "United States"] },
  "metrics": { "significance": 0.82, "article_count": 12, "linked_event_count": 2, "max_linked_event_significance": 0.76 },
  "has_events": true, "has_fatalities": false, "fatalities": 0,
  "linked_events": [ { "id": "cameoplus_20260417_example", "title": "Example linked Event" } ],
  "entity_refs": [ { "id": "Tokyo", "name": "Tokyo", "type": "LOCATION", "wikipedia_url": "https://en.wikipedia.org/wiki/Tokyo" } ],
  "top_articles": [ { "url": "https://example.com/article", "title": "Example article", "domain": "example.com", "rank": 1 } ]
}

Field	Description
`id`	Stable v2 Story cluster identifier.
`url`	Public GDELT Cloud Story URL for citation.
`title`, `story_date`	Cluster headline and cluster date.
`category`, `subcategory`	Story category and linked-Event subcategory context when available.
`geo`	Primary geography inferred through linked Events.
`geo_context`	Location country plus actor-origin countries from linked Events.
`metrics`	Story significance, article volume, linked Event count, and max linked Event significance.
`has_events`, `linked_events`	Whether structured Events link to the Story, plus up to 10 linked Event refs.
`has_fatalities`, `fatalities`	Whether linked Events include fatalities, plus total linked fatalities.
`entity_refs`	Linked Entities with names, types, and Wikipedia URLs when available.
`top_articles`	Top 3 inline source articles for evidence preview.

Summary buckets

The Event summary bucket and Story summary bucket are returned by GET /api/v2/events/summary and GET /api/v2/stories/summary. Buckets carry simple counts plus nested aggregate statistics (metrics / metric_stats) for the inputs behind significance: Goldstein scale/severity, CAMEO+ magnitude/systemic/propagation/market, confidence, article evidence, and fatality counts/rates.

{
  "success": true,
  "group_by": "country",
  "data": [
    {
      "key": "France",
      "group_by": "country",
      "event_count": 12,
      "conflict_event_count": 4,
      "cameoplus_event_count": 8,
      "fatality_event_count": 2,
      "fatalities": 6,
      "article_count": 40,
      "metrics": {
        "significance": { "avg": 0.42, "max": 0.91, "min": 0.05 },
        "goldstein_scale": { "avg": -3.8, "min": -8, "max": 2, "avg_severity": 4.2 },
        "cameoplus": { "magnitude": { "avg": 6.1, "min": 1.2, "max": 9 } },
        "article_count": { "total": 40, "avg": 3.333, "min": 1, "max": 12 },
        "fatalities": { "events": 2, "rate": 0.1667, "total": 6 }
      }
    }
  ]
}

Story summary buckets use the same envelope and add story_count, stories_with_events, story_only_count, linked-event counts, avg_recency_score, and nested metrics.linked_events. linked_event_count is the number of Story-to-Event links, not a second Event total — use event_count from Event summaries for distinct Events. Summary endpoints do not accept search.

Articles, entities, admin1, and errors

Story article rows include source domain, domain_avatar_url, image_url (when available), rank, and role. Entity cards are canonical, deduplicated by Wikipedia URL — multiple raw-name variants (“Trump” + “Donald Trump”) collapse to one card; only People and Organizations with linked Wikipedia pages are surfaced. The id is a universal canonical id — an e_… id when the entity exists in the cross-source reference spine (the same id GET /api/v2/search returns), otherwise a wiki:… id for the news-only tail. Either form round-trips on every entity-taking endpoint (/events?entity=, /entity-tone, /share-of-voice, /gov/awards?entity=, entity detail), so you can chain calls without remapping. The Wikipedia URL is still returned as the wikipedia_url field.

{
  "id": "wiki:3f2a1c9b7e5d4a6f8c02",
  "url": "https://gdeltcloud.com/entities/person-example-person",
  "name": "Example Person",
  "type": "person",
  "wikipedia_url": "https://en.wikipedia.org/wiki/Example_Person",
  "metrics": { "article_count": 20, "story_count": 8, "event_count": 3 }
}

Raw per-article mention counts and entity salience scores are not part of the v2 entity contract. GDELT Cloud surfaces aggregated Story, Article, and Event counts as the canonical activity signals.

GET /api/v2/geo/admin1 returns a per-country list:

{ "success": true, "country": "France", "admin1": ["Bretagne", "Ile-de-France"], "source": "gdelt_cloud.events" }

Standard error responses carry error, a stable code, and details with accepted_values, nearest_values when practical, and a corrected example so agents can retry without guessing:

{
  "success": false,
  "error": "Invalid continent. Use one of: Africa, Asia, Europe, North America, South America, Oceania",
  "code": "INVALID_CONTINENT",
  "details": {
    "param": "continent",
    "invalid_value": "Atlantis",
    "accepted_values": ["Africa", "Asia", "Europe", "North America", "South America", "Oceania"],
    "example": "?continent=Asia"
  }
}

subcategory requires its parent category; for CAMEO+ categories, prefer stable event codes such as TE01 over label text. The legacy event_family and domain parameters are still accepted but deprecated — category implies Conflict vs. CAMEO+.

Entity aliases and resolution

GDELT Cloud resolves observed names — reordered names, initials, acronyms, common abbreviations — to a single canonical entity through a proprietary resolution layer. Wikipedia-linked entities carry stable canonical identifiers. Newly observed candidates enter the registry as needs_review and are promoted to active once they meet confidence criteria, so workflows can distinguish “known entity with no score yet” from “entity not found.”

Finding an entity when you don’t know the exact name

GET /api/v2/entities/resolve?q=<name>&scope=all

This is the fuzzy “find the entity” step — start here whenever you have a (possibly misspelled or abbreviated) name rather than an id. scope chooses which registries to search:

scope=media (default) — news-resolved entities only (people & organizations seen in coverage).
scope=reference — the structured registry only (GEM energy owners, SEC/EDGAR filers, restricted-party list entries, China financiers).
scope=all — everything: news + GEM + SEC/EDGAR + lists + China, deduplicated and ranked.

It returns ranked candidates (entity_id, display name, type, country, match reason, score). Resolve once, then fan out across the event, energy, screening, and filings surfaces using the shared entity_id. The matching index covers the full registry even for entities with no Wikipedia page yet.

Ranking

The default sort is sort=significance. Event significance is a family-scoped weighted blend, renormalized so every event family spans a true 0–1: each event’s raw total is divided by the maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90, other CAMEO+ domains 0.65).

Applies to	Weights
All events	Goldstein severity `0.25` · article evidence `0.05` · confidence `0.05`
Conflict only	fatalities `0.55` (log-scaled by body count, saturating around 100 deaths) · civilian targeting `0.10`
CAMEO+ only	magnitude `0.20` · systemic importance `0.15` · propagation potential `0.10` · market sensitivity `0.10`

When magnitude is unmeasured, both its term and its 0.20 weight are dropped for that event. The four CAMEO+ inputs are rubric scores produced by fixed published formulas — ordinal ranking signals, not measurements, probabilities, or predicted price moves (see Event metric filters). goldstein_scale is the signed −10…+10 scale; goldstein_severity is abs(goldstein_scale) and exists as an aggregate/statistical helper for significance inputs. Story significance combines linked-Event significance, capped article count, and recency. Use sort=recent when freshness matters more than significance. goldstein_scale is exposed as one canonical public Event metric — present for all Conflict Events and CAMEO+ POLITICAL Events, null for non-political CAMEO+ domains where it is not meaningful.

Facilities

Events

Stories

Entities

Geography

Reference Data

Government

Energy

Briefs

Filings

Macro Finance

Maritime

Media Intelligence

Screening and Reference

China

Unified Search

AI Compute

Concepts & Response Objects

Authentication

Result coverage

Geography

Bounding box

Response objects

Event card

Story card

Summary buckets

Articles, entities, admin1, and errors

Entity aliases and resolution

Finding an entity when you don’t know the exact name

Ranking

​Authentication

​Result coverage

​Geography

​Bounding box

​Response objects

​Event card

​Story card

​Summary buckets

​Articles, entities, admin1, and errors

​Entity aliases and resolution

​Finding an entity when you don’t know the exact name

​Ranking

Authentication

Result coverage

Geography

Bounding box

Response objects

Event card

Story card

Summary buckets

Articles, entities, admin1, and errors

Entity aliases and resolution

Finding an entity when you don’t know the exact name

Ranking