GDELT CloudGDELT Cloud
Country and Sector Monitoring

Monitor countries, sectors, and issue domains.

Track machine-readable event flow by geography, Event family, CAMEO+ domain, significance, and linked Stories so recurring monitoring can move faster than manual news review.

Tutorial path
Agent task

Build a daily Taiwan technology monitor: check the trend, pull significant CAMEO+ technology Events, then attach the latest Story clusters for evidence.

1
Define the monitor scope

The same filter can drive a script, a dashboard, an agent run, or a future daily brief.

2
Check the trend buckets

The response returns date buckets with counts and aggregate metrics.

3
Pull significant Events

The monitor has structured records with significance, magnitude, market sensitivity, and linked Stories.

4
Attach latest Stories for evidence

The monitor can show what happened, why it matters, and which source clusters support it.

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

    Define the monitor scope

    Start with a practical saved filter: one country, one generated Event family, and one CAMEO+ domain.

    The same filter can drive a script, a dashboard, an agent run, or a future daily brief.
    REST filter setup
    python
    import os
import httpx

API_KEY = os.environ["GDELT_API_KEY"]

BASE_FILTERS = {
    "country": "Taiwan",
    "event_family": "cameoplus",
    "domain": "TECHNOLOGY",
}

client = httpx.Client(
    base_url="https://gdeltcloud.com",
    timeout=30,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Accept": "application/json",
    },
)
    Expected setup result
    text
    No data call runs in this step.
The monitor scope is Taiwan + CAMEO+ + TECHNOLOGY.
  2. Step 2

    Check the trend buckets

    Use a summary call first so the monitor knows whether the signal is rising, falling, or sparse before drilling into records.

    The response returns date buckets with counts and aggregate metrics.
    REST Event summary
    python
    params = {
    **BASE_FILTERS,
    "group_by": "date",
    "days": 7,
    "limit": 7,
}

r = client.get("/api/v2/events/summary", params=params)
r.raise_for_status()
trend = r.json()
    Representative summary response
    json
    {
  "success": true,
  "group_by": "date",
  "data": [
    {
      "key": "2026-05-07",
      "group_by": "date",
      "event_count": 14,
      "conflict_event_count": 0,
      "cameoplus_event_count": 14,
      "fatality_event_count": 0,
      "fatalities": 0,
      "fatality_event_rate": 0,
      "country_count": 1,
      "region_count": 1,
      "article_count": 96,
      "avg_article_count": 6.857,
      "min_article_count": 1,
      "max_article_count": 24,
      "avg_significance": 0.48,
      "max_significance": 0.77,
      "min_significance": 0.21,
      "avg_goldstein_scale": null,
      "min_goldstein_scale": null,
      "max_goldstein_scale": null,
      "avg_goldstein_severity": null,
      "min_goldstein_severity": null,
      "max_goldstein_severity": null,
      "avg_magnitude": 5.4,
      "min_magnitude": 3.1,
      "max_magnitude": 6.2,
      "avg_systemic_importance": 0.61,
      "min_systemic_importance": 0.34,
      "max_systemic_importance": 0.72,
      "avg_propagation_potential": 0.49,
      "min_propagation_potential": 0.22,
      "max_propagation_potential": 0.64,
      "avg_market_sensitivity": 0.42,
      "min_market_sensitivity": 0.18,
      "max_market_sensitivity": 0.58,
      "avg_confidence": 0.91,
      "min_confidence": 0.84,
      "max_confidence": 0.97,
      "metrics": {
        "significance": {
          "avg": 0.48,
          "max": 0.77,
          "min": 0.21
        },
        "goldstein_scale": {
          "avg": null,
          "min": null,
          "max": null,
          "avg_severity": null
        },
        "goldstein_severity": {
          "avg": null,
          "min": null,
          "max": null
        },
        "cameoplus": {
          "magnitude": {
            "avg": 5.4,
            "max": 6.2,
            "min": 3.1
          },
          "systemic_importance": {
            "avg": 0.61,
            "max": 0.72,
            "min": 0.34
          },
          "propagation_potential": {
            "avg": 0.49,
            "max": 0.64,
            "min": 0.22
          },
          "market_sensitivity": {
            "avg": 0.42,
            "max": 0.58,
            "min": 0.18
          }
        },
        "confidence": {
          "avg": 0.91,
          "max": 0.97,
          "min": 0.84
        },
        "article_count": {
          "total": 96,
          "avg": 6.857,
          "min": 1,
          "max": 24
        },
        "fatalities": {
          "events": 0,
          "rate": 0,
          "total": 0
        }
      },
      "metric_stats": {
        "significance": {
          "avg": 0.48,
          "max": 0.77,
          "min": 0.21
        },
        "goldstein_scale": {
          "avg": null,
          "min": null,
          "max": null,
          "avg_severity": null
        },
        "goldstein_severity": {
          "avg": null,
          "min": null,
          "max": null
        },
        "cameoplus": {
          "magnitude": {
            "avg": 5.4,
            "max": 6.2,
            "min": 3.1
          },
          "systemic_importance": {
            "avg": 0.61,
            "max": 0.72,
            "min": 0.34
          },
          "propagation_potential": {
            "avg": 0.49,
            "max": 0.64,
            "min": 0.22
          },
          "market_sensitivity": {
            "avg": 0.42,
            "max": 0.58,
            "min": 0.18
          }
        },
        "confidence": {
          "avg": 0.91,
          "max": 0.97,
          "min": 0.84
        },
        "article_count": {
          "total": 96,
          "avg": 6.857,
          "min": 1,
          "max": 24
        },
        "fatalities": {
          "events": 0,
          "rate": 0,
          "total": 0
        }
      }
    }
  ]
}
  3. Step 3

    Pull significant Events

    After the summary confirms there is signal, get the highest-significance machine-readable Events.

    The monitor has structured records with significance, magnitude, market sensitivity, and linked Stories.
    REST Event records
    python
    params = {
    **BASE_FILTERS,
    "sort": "significance",
    "limit": 10,
}

r = client.get("/api/v2/events", params=params)
r.raise_for_status()
events = r.json()["data"]
    Representative Event response
    json
    {
  "success": true,
  "data": [
    {
      "id": "cameoplus_taiwan_tech_001",
      "url": "https://gdeltcloud.com/events/taiwan-semiconductor-technology-policy-signal--cameoplus_taiwan_tech_001",
      "primary_story_url": "https://gdeltcloud.com/stories/semiconductor-policy-and-technology-supply-chain-story-cluster-storytai",
      "family": "cameoplus",
      "title": "Taiwan semiconductor technology policy signal",
      "summary": "CAMEO+ technology Event card for a Taiwan semiconductor policy signal.",
      "event_date": "2026-05-07",
      "category": "TECHNOLOGY",
      "subcategory": "Technology policy or investment signal",
      "domain": "TECHNOLOGY",
      "event_code": "TECH_POLICY",
      "geo": {
        "country": "Taiwan",
        "region": "East Asia",
        "continent": "Asia",
        "admin1": null,
        "location": "Taiwan",
        "latitude": 23.6978,
        "longitude": 120.9605
      },
      "geo_context": {
        "location_country": "Taiwan",
        "actor_origin_countries": [
          "Taiwan"
        ]
      },
      "actors": [
        {
          "name": "Government officials",
          "country": "Taiwan",
          "role": "source"
        },
        {
          "name": "Semiconductor industry",
          "country": "Taiwan",
          "role": "target"
        }
      ],
      "metrics": {
        "significance": 0.77,
        "goldstein_scale": null,
        "magnitude": 6.2,
        "systemic_importance": 0.72,
        "propagation_potential": 0.64,
        "market_sensitivity": 0.58,
        "confidence": 0.93,
        "article_count": 24
      },
      "has_fatalities": false,
      "fatalities": 0,
      "story_refs": [
        {
          "id": "story_taiwan_tech_001",
          "url": "https://gdeltcloud.com/stories/semiconductor-policy-and-technology-supply-chain-story-cluster-storytai",
          "title": "Semiconductor policy and technology supply-chain story cluster",
          "story_date": "2026-05-07",
          "article_count": 24
        }
      ],
      "entity_refs": [
        {
          "id": "https://en.wikipedia.org/wiki/Taiwan_Semiconductor_Manufacturing_Company",
          "name": "Taiwan Semiconductor Manufacturing Company",
          "type": "organization",
          "wikipedia_url": "https://en.wikipedia.org/wiki/Taiwan_Semiconductor_Manufacturing_Company",
          "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

    Attach latest Stories for evidence

    Pair the structured Events with clustered narrative evidence so the monitor is useful to humans and agents.

    The monitor can show what happened, why it matters, and which source clusters support it.
    REST Story clusters
    python
    params = {
    "country": "Taiwan",
    "domain": "TECHNOLOGY",
    "has_events": True,
    "sort": "significance",
    "limit": 10,
}

r = client.get("/api/v2/stories", params=params)
r.raise_for_status()
stories = r.json()["data"]
    Representative Story response
    json
    {
  "success": true,
  "data": [
    {
      "id": "story_taiwan_tech_001",
      "url": "https://gdeltcloud.com/stories/semiconductor-policy-and-technology-supply-chain-story-cluster-storytai",
      "title": "Semiconductor policy and technology supply-chain story cluster",
      "story_date": "2026-05-07",
      "category": "cameoplus_technology",
      "subcategory": null,
      "geo": {
        "country": "Taiwan",
        "region": "East Asia",
        "continent": "Asia",
        "admin1": null,
        "location": "Taiwan",
        "latitude": 23.6978,
        "longitude": 120.9605
      },
      "geo_context": {
        "location_country": "Taiwan",
        "actor_origin_countries": [
          "Taiwan"
        ]
      },
      "metrics": {
        "significance": 0.74,
        "article_count": 24,
        "linked_event_count": 4,
        "max_linked_event_significance": 0.77
      },
      "has_events": true,
      "has_fatalities": false,
      "fatalities": 0,
      "linked_events": [
        {
          "id": "cameoplus_taiwan_tech_001",
          "title": "Taiwan semiconductor technology policy signal"
        }
      ],
      "entity_refs": [
        {
          "id": "https://en.wikipedia.org/wiki/Taiwan_Semiconductor_Manufacturing_Company",
          "name": "Taiwan Semiconductor Manufacturing Company",
          "type": "organization",
          "wikipedia_url": "https://en.wikipedia.org/wiki/Taiwan_Semiconductor_Manufacturing_Company",
          "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"
}

Workflow fit

Country watchlists for security, policy, macro, and operational risk teams.

Sector monitors for technology, infrastructure, health, environment, and economic signals.

Recurring brief inputs that keep analysts focused on what changed.

Output widgets

Trend bucket
7d

Summaries return date buckets with count and aggregate metric shape.

Signal rank
0.77

Event records can be sorted by GDELT Cloud significance.

Daily brief
Soon

Use the same filter as an input for recurring Brief workflows.