API v2 is the simplified user-facing interface for generated GDELT Cloud products. v1 remains available for existing integrations; v2 is the recommended surface for new dashboards, monitoring workflows, and ad-hoc search. v2 focuses on:Documentation Index
Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
Use this file to discover all available pages before exploring further.
- Generated structured Events:
conflictandcameoplus. - Generated clustered Stories.
- Generated metrics for Events and Stories.
- Entity discovery and entity-to-Story/Event linking.
scope, detail, geo_scope, event_readiness, cluster_certainty, language, quad_class, or raw total_events.
Authentication
Use the same API key format as v1:Geography
Use plain English country names in docs and examples: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 country-list 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, use geo_context.actor_origin_countries to see why the record matched. For Stories, geo_context.actor_origin_countries is returned for context but does not drive the Story geo filter.
Discover valid admin1 values one country at a time:
Response Objects
List endpoints return a success envelope withdata and pagination; detail endpoints return a single data object; summary endpoints return group_by and grouped data buckets.
Quality Defaults
Event and Story list/summary endpoints default toconfidence_profile=precise, which favors analyst-ready, non-repetitive results. Use confidence_profile=loose when you explicitly need exhaustive/raw retrieval.
Profiles:
strictest: highest precision. Stories must be primary/strong and have at least two articles orsingleton_score >= 0.75.precise: default. Events requiremetrics.confidence >= 0.75and linked primary/strong Story evidence; Stories require primary/strong Story families.balanced: broader quality filtering for exploration.loose: exhaustive mode; disables default Event/Story quality filters.
min_confidence=0..1 overrides the Event confidence threshold implied by the profile. Detail endpoints remain exhaustive by ID: GET /api/v2/events/{event_id} and GET /api/v2/stories/{story_id} still resolve known records even if they would not appear in the default feed.
Event card
Returned byGET /api/v2/events and GET /api/v2/events/{event_id}.
| 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 | Product taxonomy fields. Conflict Events use conflict event/sub-event types; CAMEO+ Events use generated domain/event descriptions where applicable. |
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 generated metric inputs. |
has_fatalities, fatalities | Fatality flag and count. |
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 article lists. |
Story card
Returned byGET /api/v2/stories and GET /api/v2/stories/{story_id}.
| 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. |
Event summary bucket and Story summary bucket
Returned byGET /api/v2/events/summary and GET /api/v2/stories/summary.
| Field | Description |
|---|---|
key | Bucket value for the selected group_by. Country keys are normalized to plain English names. |
group_by | Concrete grouping label returned by the API. |
event_count, story_count | Number of Events or Stories in the bucket. |
conflict_event_count, cameoplus_event_count | Event-family counts for Event summaries. |
article_count, avg_article_count, min_article_count, max_article_count | Total, average, min, and max article evidence volume. |
fatality_event_count, stories_with_fatalities, fatalities, fatality_event_rate, fatality_story_rate | Fatality coverage fields. |
country_count, region_count | Distinct geography counts represented in the bucket. |
avg_*, max_*, min_* | Flat aggregate fields retained for simple clients. |
metrics | Nested aggregate statistics for significance and its input metrics. |
metric_stats | Alias of metrics for clients that prefer explicit statistical naming. |
story_count, stories_with_events, story_only_count, linked_event_count, min_linked_event_count, avg_linked_event_count, max_linked_event_count, avg_recency_score, and nested metrics.linked_events for linked Event significance, Goldstein, CAMEO+, confidence, and market-sensitivity aggregates. linked_event_count is the number of Story-to-Event links in the Story bucket, not a second Event total; use event_count from Event summaries for distinct Events.
Articles, Entities, Admin1, And Errors
Story article responses:GET /api/v2/geo/admin1 returns:
Events
List Events
date_start,date_end:YYYY-MM-DDcountry,region,continent,admin1event_family:conflictorcameopluscategory,subcategory;categoryaccepts a single value or comma-separated values such asProtests,CRIMEdomain:POLITICAL,ECONOMIC,CORPORATE,TECHNOLOGY,INFRASTRUCTURE,HEALTH,INFORMATION,ENVIRONMENT,CRIMEhas_fatalities:trueorfalseconfidence_profile:strictest,precisedefault,balanced, orloosemin_confidence: Event confidence threshold override, from0to1search: free textsort:significanceorrecentlimit,cursor
id, url, primary_story_url, family, title, summary, event_date, category fields, normalized geo with admin1, geo_context, actors, metrics, fatality fields, linked Stories, linked Entities, and top_articles.
By default, Events use confidence_profile=precise: metrics.confidence >= 0.75, plus linked canonical Story evidence with visibility_tier=primary and story_family_grade=strong. Add confidence_profile=loose for exhaustive retrieval, or add min_confidence=0.9 when you want a custom Event confidence floor.
Country, region, and continent filters match Events by either event location country or actor-origin country. Use geo.location_country and geo_context.actor_origin_countries to label results as location matches, actor matches, or both in dashboards.
Use url or primary_story_url as the public GDELT Cloud citation when present. story_refs[].url points to the linked public Story page.
top_articles is always limited to the top 3 inline articles.
Fetch Event
Event Summary
group_by=date|country|region|continent|category|subcategory. Summary buckets include the simple counts plus aggregate metric statistics for the generated inputs behind Event significance: Goldstein scale/severity, CAMEO+ magnitude, systemic importance, propagation potential, market sensitivity, confidence, article evidence, and fatality counts/rates.
Event summaries use the same confidence_profile and min_confidence defaults as Event lists. Summary endpoints do not accept search. Use the list endpoint for semantic retrieval, then call the summary endpoint with structured filters.
Example:
Stories
List Stories
date_start,date_endcountry,region,continent,admin1category,event_category,subcategory,domainhas_events,has_fatalitiesconfidence_profile:strictest,precisedefault,balanced, orloosearticle_count_min,article_count_maxsearchsort:significanceorrecentlimit,cursor
id, url, title, story_date, category fields, normalized geo with admin1, geo_context, metrics, linked Event refs, Entity refs, fatality flags, and top_articles.
By default, Stories use confidence_profile=precise: visibility_tier=primary and story_family_grade=strong. Story list and summary endpoints also collapse obvious duplicate Story families before pagination or aggregation, preferring the strongest primary/readiness/certainty/article-count representative. Add confidence_profile=loose when you need exhaustive retrieval.
Use category for Story cluster categories. Use event_category when you want Stories whose linked Events match a top-level Conflict category such as Protests or a CAMEO+ domain such as POLITICAL or CRIME. event_category accepts a single value or comma-separated values.
Use url as the public GDELT Cloud citation for the cluster. Use top_articles as direct source evidence.
Fetch Story
Fetch Story Articles
Story Summary
group_by=date|country|region|continent|category|subcategory. Summary buckets include Story counts plus aggregate statistics for Story significance inputs: article volume, linked Event counts and metrics, linked Event Goldstein/CAMEO+ aggregates, recency, and fatalities. Story summaries use the same confidence_profile defaults and duplicate-family collapse as Story lists. Use event_category to summarize Stories through linked Event categories without confusing those with Story cluster categories.
Summary endpoints do not accept search. Use the list endpoint for semantic retrieval, then call the summary endpoint with structured filters.
Entities
url values when a GDELT Cloud entity page can be constructed, plus linked Story/Event refs. The first v2 pass focuses on clean discovery and linking; deeper entity redesign is deferred.
Ranking
The default sort issort=significance.
Event significance combines Goldstein severity where meaningful, CAMEO+ magnitude/systemic/propagation/market metrics where present, fatality presence for Conflict Events, article evidence volume, and confidence.
The Event significance formula is:
Goldstein severity 25% + CAMEO+ magnitude 20% + systemic importance 15% + propagation potential 10% + market sensitivity 10% + fatalities 10% + article evidence 5% + confidence 5%.
goldstein_scale is the signed -10 to +10 scale. goldstein_severity is abs(goldstein_scale) and exists only as an aggregate/statistical helper for significance inputs.
Story significance combines linked Event significance, capped article count, and recency. Use sort=recent when freshness is more important than significance.
goldstein_scale is public:
- Present for all Conflict Events.
- Present for CAMEO+
POLITICALEvents. - Null for non-political CAMEO+ domains where the metric is not meaningful.
- Exposed as one canonical public Event metric. Family-specific physical source columns remain internal implementation details.
Recommended Usage Cookbook
Use Events when you need structured incidents, actors, event category/subcategory, fatalities, Goldstein scale, or event-level metrics. Use Stories when you need a clustered narrative with top article evidence. Use summaries for dashboard totals and trend charts, then drill down into Events or Stories with the same filters. Prefer these defaults:- Use
sort=significancefor monitoring and dashboards. - Use
sort=recentwhen freshness matters more than importance. - Use plain English geography in docs and apps, for example
country=United States. - When writing code, pass query parameters through your HTTP client’s
paramsoption orURLSearchParamsinstead of hand-building URLs. Spaces do not need manual%20handling in code: clients encodeUnited Statescorrectly, and the API decodes both%20and+in query strings. - Use
date_startanddate_endexplicitly. For live monitoring, query the latest populated day or trailing 7-30 day window. - Use
observed_startandobserved_endwhen you need an ingestion/updated-at window, such as a live dashboard for items observed today. - Keep the default
confidence_profile=precisefor analyst-facing feeds. Useconfidence_profile=looseonly when you need exhaustive/raw retrieval, and usemin_confidenceon Event list/summary endpoints when you need a custom confidence floor. - Use
searchfor true semantic retrieval on list endpoints only: v2 embeds the query text, applies the structured filters as the candidate set, and ranks records by cosine similarity against stored Event or Story embeddings. Summary endpoints do not acceptsearch. - Use
admin1only after discovering valid values through/api/v2/geo/admin1?country=.... - Treat inline
top_articlesas evidence preview only; use/api/v2/stories/{story_id}/articlesfor the full paginated source list.
Country, Region, Or Continent Monitoring
Infrastructure Events
Use CAMEO+domain=INFRASTRUCTURE as the canonical pattern:
Semantic Event Search
Protests Today Or Recently
For a current list:New Data Center Projects In Asia
Use Stories first because this is a narrative discovery task. Keeparticle_count_min=1 for emerging project discovery; raise it only when you want more source volume.

