Skip to main content

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.

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:
  • Generated structured Events: conflict and cameoplus.
  • Generated clustered Stories.
  • Generated metrics for Events and Stories.
  • Entity discovery and entity-to-Story/Event linking.
v2 does not expose raw GDELT-only fields or legacy tuning knobs such as scope, detail, geo_scope, event_readiness, cluster_certainty, language, quad_class, or raw total_events.

Authentication

Use the same API key format as v1:
Authorization: Bearer gdelt_sk_...

Geography

Use plain English country names in docs and examples:
country=France
country=United States
country=South Korea
The backend also accepts ISO-3 and legacy FIPS aliases for compatibility, but responses normalize country output to the plain English name. 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:
curl "https://gdeltcloud.com/api/v2/geo/admin1?country=France" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

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"
  }
}

Quality Defaults

Event and Story list/summary endpoints default to confidence_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 or singleton_score >= 0.75.
  • precise: default. Events require metrics.confidence >= 0.75 and 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.
For Event list and Event summary endpoints, 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 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,
  "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
    }
  ]
}
FieldDescription
idStable v2 Event identifier.
url, primary_story_urlPublic GDELT Cloud Story URL for citation when the Event has a linked Story.
familyconflict or cameoplus.
title, summaryGenerated Event headline and concise summary.
event_dateEvent date in YYYY-MM-DD.
category, subcategoryProduct taxonomy fields. Conflict Events use conflict event/sub-event types; CAMEO+ Events use generated domain/event descriptions where applicable.
domainCAMEO+ domain, or CONFLICT for conflict Events.
event_codeSource event id, CAMEO+ event code, or null.
geoPrimary Event location.
geo_contextExplains broad geography matches, especially actor-origin matches.
actorsEvent actors with name, normalized country, and role.
metricsEvent significance and generated metric inputs.
has_fatalities, fatalitiesFatality flag and count.
story_refsLinked Story references with public URLs.
entity_refsLinked Entities with names, types, and Wikipedia URLs when available.
top_articlesTop 3 inline source articles. Use the Story articles endpoint for full article 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
    }
  ]
}
FieldDescription
idStable v2 Story cluster identifier.
urlPublic GDELT Cloud Story URL for citation.
title, story_dateCluster headline and cluster date.
category, subcategoryStory category and linked-Event subcategory context when available.
geoPrimary geography inferred through linked Events.
geo_contextLocation country plus actor-origin countries from linked Events.
metricsStory significance, article volume, linked Event count, and max linked Event significance.
has_events, linked_eventsWhether structured Events link to the Story, plus up to 10 linked Event refs.
has_fatalities, fatalitiesWhether linked Events include fatalities, plus total linked fatalities.
entity_refsLinked Entities with names, types, and Wikipedia URLs when available.
top_articlesTop 3 inline source articles for evidence preview.

Event summary bucket and Story summary bucket

Returned by GET /api/v2/events/summary and GET /api/v2/stories/summary.
{
  "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,
      "fatality_event_rate": 0.1667,
      "country_count": 1,
      "region_count": 1,
      "article_count": 40,
      "avg_article_count": 3.333,
      "min_article_count": 1,
      "max_article_count": 12,
      "avg_significance": 0.42,
      "max_significance": 0.91,
      "min_significance": 0.05,
      "avg_goldstein_scale": -3.8,
      "metrics": {
        "significance": { "avg": 0.42, "max": 0.91, "min": 0.05 },
        "goldstein_scale": { "avg": -3.8, "min": -8, "max": 2, "avg_severity": 4.2 },
        "goldstein_severity": { "avg": 4.2, "min": 0.5, "max": 8 },
        "cameoplus": {
          "magnitude": { "avg": 6.1, "min": 1.2, "max": 9 },
          "systemic_importance": { "avg": 0.52, "min": 0.11, "max": 0.9 },
          "propagation_potential": { "avg": 0.47, "min": 0.07, "max": 0.81 },
          "market_sensitivity": { "avg": 0.31, "min": 0.03, "max": 0.75 }
        },
        "confidence": { "avg": 0.83, "min": 0.44, "max": 0.98 },
        "article_count": { "total": 40, "avg": 3.333, "min": 1, "max": 12 },
        "fatalities": { "events": 2, "rate": 0.1667, "total": 6 }
      },
      "metric_stats": {
        "significance": { "avg": 0.42, "max": 0.91, "min": 0.05 }
      }
    }
  ]
}
FieldDescription
keyBucket value for the selected group_by. Country keys are normalized to plain English names.
group_byConcrete grouping label returned by the API.
event_count, story_countNumber of Events or Stories in the bucket.
conflict_event_count, cameoplus_event_countEvent-family counts for Event summaries.
article_count, avg_article_count, min_article_count, max_article_countTotal, average, min, and max article evidence volume.
fatality_event_count, stories_with_fatalities, fatalities, fatality_event_rate, fatality_story_rateFatality coverage fields.
country_count, region_countDistinct geography counts represented in the bucket.
avg_*, max_*, min_*Flat aggregate fields retained for simple clients.
metricsNested aggregate statistics for significance and its input metrics.
metric_statsAlias of metrics for clients that prefer explicit statistical naming.
Story summary buckets use the same envelope and include 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:
{
  "success": true,
  "data": [
    {
      "id": "article_123",
      "url": "https://example.com/article",
      "title": "Example article",
      "domain": "example.com",
      "article_date": "2026-04-17",
      "rank": 1,
      "role": "representative"
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": null,
    "next_cursor": null
  }
}
Entity list responses return Entity cards:
{
  "id": "person:Example%20Person",
  "url": "https://gdeltcloud.com/entity-geg/person/Example%20Person",
  "name": "Example Person",
  "type": "person",
  "wikipedia_url": "https://en.wikipedia.org/wiki/Example_Person",
  "metrics": {
    "article_count": 20,
    "mention_count": 45,
    "story_count": 8,
    "event_count": 3,
    "avg_salience": 0.41
  }
}
Entity detail responses add linked references:
{
  "success": true,
  "data": {
    "id": "person:Example%20Person",
    "url": "https://gdeltcloud.com/entity-geg/person/Example%20Person",
    "name": "Example Person",
    "type": "person",
    "wikipedia_url": "https://en.wikipedia.org/wiki/Example_Person",
    "metrics": {
      "article_count": 20,
      "mention_count": 45,
      "avg_salience": 0.41
    },
    "story_refs": [
      {
        "id": "story_20260417_example",
        "title": "Example story",
        "story_date": "2026-04-17",
        "category": "politics",
        "article_count": 4,
        "entity_mentions": 3,
        "url": "https://gdeltcloud.com/story/example-story"
      }
    ],
    "event_refs": [
      {
        "id": "conflict_20260417_example",
        "title": "Example event",
        "family": "conflict",
        "event_date": "2026-04-17",
        "story_id": "story_20260417_example",
        "story_title": "Example story",
        "entity_mentions": 2,
        "story_url": "https://gdeltcloud.com/story/example-story"
      }
    ]
  }
}
GET /api/v2/geo/admin1 returns:
{
  "success": true,
  "country": "France",
  "admin1": ["Bretagne", "Ile-de-France"],
  "source": "gdelt_cloud.events"
}
Standard error responses:
{
  "success": false,
  "error": "Invalid continent. Use one of: Africa, Asia, Europe, North America, South America, Oceania",
  "code": "INVALID_CONTINENT"
}

Events

List Events

GET /api/v2/events
Common filters:
  • date_start, date_end: YYYY-MM-DD
  • country, region, continent, admin1
  • event_family: conflict or cameoplus
  • category, subcategory; category accepts a single value or comma-separated values such as Protests,CRIME
  • domain: POLITICAL, ECONOMIC, CORPORATE, TECHNOLOGY, INFRASTRUCTURE, HEALTH, INFORMATION, ENVIRONMENT, CRIME
  • has_fatalities: true or false
  • confidence_profile: strictest, precise default, balanced, or loose
  • min_confidence: Event confidence threshold override, from 0 to 1
  • search: free text
  • sort: significance or recent
  • limit, cursor
Example:
curl "https://gdeltcloud.com/api/v2/events?country=France&category=Protests&date_start=2026-04-01&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
Event cards include 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

GET /api/v2/events/{event_id}

Event Summary

GET /api/v2/events/summary
Use 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:
curl "https://gdeltcloud.com/api/v2/events/summary?region=Middle%20East&event_family=conflict&has_fatalities=true&group_by=country&date_start=2026-04-01&date_end=2026-04-17" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

Stories

List Stories

GET /api/v2/stories
Common filters:
  • date_start, date_end
  • country, region, continent, admin1
  • category, event_category, subcategory, domain
  • has_events, has_fatalities
  • confidence_profile: strictest, precise default, balanced, or loose
  • article_count_min, article_count_max
  • search
  • sort: significance or recent
  • limit, cursor
Example:
curl "https://gdeltcloud.com/api/v2/stories?continent=Asia&search=new%20data%20center%20projects&article_count_min=2&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
Story cards include 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

GET /api/v2/stories/{story_id}

Fetch Story Articles

GET /api/v2/stories/{story_id}/articles
Use this cursor endpoint for the full article list. Story list/detail endpoints only return the top 3 articles inline.

Story Summary

GET /api/v2/stories/summary
Use 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

GET /api/v2/entities
GET /api/v2/entities/{entity_id}
Entity cards and profiles include public 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 is sort=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+ POLITICAL Events.
  • 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.
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=significance for monitoring and dashboards.
  • Use sort=recent when 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 params option or URLSearchParams instead of hand-building URLs. Spaces do not need manual %20 handling in code: clients encode United States correctly, and the API decodes both %20 and + in query strings.
  • Use date_start and date_end explicitly. For live monitoring, query the latest populated day or trailing 7-30 day window.
  • Use observed_start and observed_end when you need an ingestion/updated-at window, such as a live dashboard for items observed today.
  • Keep the default confidence_profile=precise for analyst-facing feeds. Use confidence_profile=loose only when you need exhaustive/raw retrieval, and use min_confidence on Event list/summary endpoints when you need a custom confidence floor.
  • Use search for 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 accept search.
  • Use admin1 only after discovering valid values through /api/v2/geo/admin1?country=....
  • Treat inline top_articles as evidence preview only; use /api/v2/stories/{story_id}/articles for the full paginated source list.

Country, Region, Or Continent Monitoring

curl "https://gdeltcloud.com/api/v2/events?country=United%20States&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
curl "https://gdeltcloud.com/api/v2/stories?continent=Asia&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

Infrastructure Events

Use CAMEO+ domain=INFRASTRUCTURE as the canonical pattern:
curl "https://gdeltcloud.com/api/v2/events?event_family=cameoplus&domain=INFRASTRUCTURE&country=United%20States&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
curl "https://gdeltcloud.com/api/v2/events?search=attacks%20on%20energy%20infrastructure&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

Protests Today Or Recently

For a current list:
curl "https://gdeltcloud.com/api/v2/events?category=Protests,CRIME&country=India&date_start=2026-04-17&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
For a daily dashboard trend:
curl "https://gdeltcloud.com/api/v2/events/summary?category=Protests,CRIME&country=India&group_by=date&date_start=2026-04-11&date_end=2026-04-17" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

New Data Center Projects In Asia

Use Stories first because this is a narrative discovery task. Keep article_count_min=1 for emerging project discovery; raise it only when you want more source volume.
curl "https://gdeltcloud.com/api/v2/stories?continent=Asia&search=new%20data%20center%20projects&article_count_min=1&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
Then use Events if you need structured infrastructure event records:
curl "https://gdeltcloud.com/api/v2/events?event_family=cameoplus&domain=INFRASTRUCTURE&continent=Asia&search=data%20center%20projects&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

Fatal Conflict Monitoring

curl "https://gdeltcloud.com/api/v2/events?event_family=conflict&has_fatalities=true&country=Lebanon&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

Admin1 Drilldown

curl "https://gdeltcloud.com/api/v2/geo/admin1?country=United%20States" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
curl "https://gdeltcloud.com/api/v2/events?country=United%20States&admin1=District%20of%20Columbia&date_start=2026-04-11&date_end=2026-04-17&sort=significance" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"

Story Articles

Story list and detail responses return only the top 3 inline articles. Use the articles endpoint for the full source set:
curl "https://gdeltcloud.com/api/v2/stories/{story_id}/articles?limit=25" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"
curl "https://gdeltcloud.com/api/v2/stories/{story_id}/articles?limit=25&cursor={next_cursor}" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY"