GDELT CloudGDELT Cloud
API for Risk Dashboards

Add world-state intelligence without building the pipeline.

Use GDELT Cloud APIs to populate internal dashboards with structured Events, linked Stories, Entities, and evidence instead of maintaining your own news clustering and event-coding stack.

Tutorial path
Agent task

Build an Egypt/Suez risk dashboard with three widgets: an Event feed, a Story evidence rail, and an Entity context panel.

1
Build the dashboard query plan

The dashboard has three small API calls instead of a custom GDELT processing pipeline.

2
Populate the Event feed

The dashboard gets machine-readable event rows with metrics and Story references.

3
Add the evidence rail

The dashboard can show article volume, linked Events, and source previews beside the Event feed.

4
Add entity context

The dashboard can show an entity context widget for Suez with linked story and event counts.

REST API and MCP, side by side

A working Hello World path from query to product surface.

Each step shows the deterministic REST call and the agent-native MCP equivalent using the current progressive discovery wrapper.

  1. Step 1

    Build the dashboard query plan

    Map each widget to one product surface before writing UI code: Events for signal, Stories for evidence, Entities for context.

    The dashboard has three small API calls instead of a custom GDELT processing pipeline.
    REST dashboard plan
    python
    import os
import httpx

API_KEY = os.environ["GDELT_API_KEY"]

client = httpx.Client(
    base_url="https://gdeltcloud.com",
    timeout=30,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Accept": "application/json",
    },
)

QUERIES = {
    "event_feed": ("/api/v2/events", {"country": "Egypt", "sort": "significance", "limit": 10}),
    "evidence_rail": ("/api/v2/stories", {"country": "Egypt", "sort": "significance", "limit": 10}),
    "entity_context": ("/api/v2/entities", {"search": "Suez", "limit": 10}),
}
    Expected setup result
    text
    No product query runs in this step.
The dashboard will request Events, Stories, and Entities as separate widgets.
  2. Step 2

    Populate the Event feed

    Fetch the highest-significance structured Events for the selected country or exposure.

    The dashboard gets machine-readable event rows with metrics and Story references.
    REST Event feed
    python
    endpoint, params = QUERIES["event_feed"]
r = client.get(endpoint, params=params)
r.raise_for_status()
event_feed = r.json()["data"]
    Representative Event feed response
    json
    {
  "success": true,
  "data": [
    {
      "id": "cameoplus_egypt_infra_001",
      "url": "https://gdeltcloud.com/events/high-significance-infrastructure-and-corridor-risk-event--cameoplus_egypt_infra_001",
      "primary_story_url": "https://gdeltcloud.com/stories/suez-corridor-risk-and-infrastructure-story-cluster-storysue",
      "family": "cameoplus",
      "title": "High-significance infrastructure and corridor risk event",
      "summary": "Infrastructure Event card suitable for a corridor-risk dashboard feed.",
      "event_date": "2026-05-07",
      "category": "INFRASTRUCTURE",
      "subcategory": "Transport, port, or corridor disruption signal",
      "domain": "INFRASTRUCTURE",
      "event_code": "INFRA_TRANSPORT",
      "geo": {
        "country": "Egypt",
        "region": "Middle East",
        "continent": "Africa",
        "admin1": "Ismailia Governorate",
        "location": "Suez Canal corridor",
        "latitude": 30.5852,
        "longitude": 32.2654
      },
      "geo_context": {
        "location_country": "Egypt",
        "actor_origin_countries": [
          "Egypt"
        ]
      },
      "actors": [
        {
          "name": "Port authority",
          "country": "Egypt",
          "role": "source"
        },
        {
          "name": "Shipping operators",
          "country": null,
          "role": "target"
        }
      ],
      "metrics": {
        "significance": 0.81,
        "goldstein_scale": null,
        "magnitude": 6.4,
        "systemic_importance": 0.74,
        "propagation_potential": 0.69,
        "market_sensitivity": 0.63,
        "confidence": 0.9,
        "article_count": 31
      },
      "has_fatalities": false,
      "fatalities": 0,
      "story_refs": [
        {
          "id": "story_suez_001",
          "url": "https://gdeltcloud.com/stories/suez-corridor-risk-and-infrastructure-story-cluster-storysue",
          "title": "Suez corridor risk and infrastructure story cluster",
          "story_date": "2026-05-07",
          "article_count": 31
        }
      ],
      "entity_refs": [
        {
          "id": "https://en.wikipedia.org/wiki/Suez_Canal_Authority",
          "name": "Suez Canal Authority",
          "type": "organization",
          "wikipedia_url": "https://en.wikipedia.org/wiki/Suez_Canal_Authority",
          "image_url": null,
          "avatar_url": null
        }
      ],
      "top_articles": [
        {
          "url": "https://example.org/source-article",
          "title": "Representative source article",
          "domain": "example.org",
          "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.org&sz=64",
          "rank": 1,
          "image_url": null
        }
      ],
      "image_url": null
    }
  ],
  "pagination": {
    "limit": 10,
    "cursor": null,
    "next_cursor": null
  },
  "sort": "significance"
}
  3. Step 3

    Add the evidence rail

    Fetch narrative clusters so analysts can click from each dashboard signal into article-backed context.

    The dashboard can show article volume, linked Events, and source previews beside the Event feed.
    REST Story evidence
    python
    endpoint, params = QUERIES["evidence_rail"]
r = client.get(endpoint, params=params)
r.raise_for_status()
evidence_rail = r.json()["data"]
    Representative Story evidence response
    json
    {
  "success": true,
  "data": [
    {
      "id": "story_suez_001",
      "url": "https://gdeltcloud.com/stories/suez-corridor-risk-and-infrastructure-story-cluster-storysue",
      "title": "Suez corridor risk and infrastructure story cluster",
      "story_date": "2026-05-07",
      "category": "cameoplus_infrastructure",
      "subcategory": null,
      "geo": {
        "country": "Egypt",
        "region": "Middle East",
        "continent": "Africa",
        "admin1": "Ismailia Governorate",
        "location": "Suez Canal corridor",
        "latitude": 30.5852,
        "longitude": 32.2654
      },
      "geo_context": {
        "location_country": "Egypt",
        "actor_origin_countries": [
          "Egypt"
        ]
      },
      "metrics": {
        "significance": 0.76,
        "article_count": 31,
        "linked_event_count": 5,
        "max_linked_event_significance": 0.81
      },
      "has_events": true,
      "has_fatalities": false,
      "fatalities": 0,
      "linked_events": [
        {
          "id": "cameoplus_egypt_infra_001",
          "title": "High-significance infrastructure and corridor risk event"
        }
      ],
      "entity_refs": [
        {
          "id": "https://en.wikipedia.org/wiki/Suez_Canal_Authority",
          "name": "Suez Canal Authority",
          "type": "organization",
          "wikipedia_url": "https://en.wikipedia.org/wiki/Suez_Canal_Authority",
          "image_url": null,
          "avatar_url": null
        }
      ],
      "top_articles": [
        {
          "url": "https://example.org/source-article",
          "title": "Representative source article",
          "domain": "example.org",
          "domain_avatar_url": "https://www.google.com/s2/favicons?domain=example.org&sz=64",
          "rank": 1,
          "image_url": null
        }
      ],
      "image_url": null
    }
  ],
  "pagination": {
    "limit": 10,
    "cursor": null,
    "next_cursor": null
  },
  "sort": "significance"
}
  4. Step 4

    Add entity context

    Resolve places, organizations, or people into linked Entity cards so the dashboard can pivot beyond a single feed row.

    The dashboard can show an entity context widget for Suez with linked story and event counts.
    REST Entity context
    python
    endpoint, params = QUERIES["entity_context"]
r = client.get(endpoint, params=params)
r.raise_for_status()
entity_context = r.json()["data"]
    Representative Entity response
    json
    {
  "success": true,
  "data": [
    {
      "id": "https://en.wikipedia.org/wiki/Suez_Canal",
      "url": null,
      "name": "Suez Canal",
      "type": "location",
      "wikipedia_url": "https://en.wikipedia.org/wiki/Suez_Canal",
      "latest_date": "2026-05-07",
      "metrics": {
        "article_count": 42,
        "mention_count": 63,
        "story_count": 14,
        "event_count": 6,
        "avg_salience": 0.0412
      },
      "image_url": null,
      "avatar_url": null,
      "wikipedia": {
        "thumbnail_url": null,
        "description": "Artificial sea-level waterway in Egypt connecting the Mediterranean Sea and the Red Sea.",
        "page_url": "https://en.wikipedia.org/wiki/Suez_Canal"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "cursor": null,
    "next_cursor": null
  }
}

Workflow fit

Executive risk dashboards with structured geopolitical event feeds.

Exposure monitors for locations, suppliers, sectors, companies, or chokepoints.

Internal analyst tools backed by clean API responses instead of raw news plumbing.

Output widgets

Event feed
10

Sorted by significance for the selected country, sector, or exposure.

Evidence rail
31

Story article volume and linked source evidence for analyst review.

Entity context
Suez

Linked Entity context with related Story and Event counts for drilldown.