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 reporting context for Suez; this search does not establish a cross-dataset identity.

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 named tools.

Example responses are illustrative snapshots. Run the calls and check the returned query window, coverage, and applied filters for current results.

  1. Step 1

    Build the dashboard query plan

    Map each widget to one product surface: Events for signal, Stories for evidence, and Entities for people and places appearing in reporting.

    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", "country_match": "location", "days": 7, "sort": "significance", "limit": 10}),
    "evidence_rail": ("/api/v2/stories", {"country": "Egypt", "country_match": "location", "days": 7, "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 significant Events located in the selected country. Inspect meta.query_window and meta.coverage before interpreting a time series.

    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"]
    Illustrative Event response shape (May 2026)
    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"]
    Illustrative Story response shape (May 2026)
    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

    Find Entities appearing in reporting about Suez. For a cross-source identity, separately use /api/v2/search and inspect the candidates.

    The dashboard can show reporting context for Suez; this search does not establish a cross-dataset identity.
    REST Entity context
    python
    endpoint, params = QUERIES["entity_context"]
r = client.get(endpoint, params=params)
r.raise_for_status()
entity_context = r.json()["data"]
    Illustrative reporting Entity response (May 2026)
    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

Entities mentioned in reporting, with Story and Event counts for drilldown.