Tutorial: GDELT Global Events

Media

Data source: GDELT Project

Overview

GDELT Global Events wraps GDELT Project, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-gdelt": {
      "url": "https://context.gnist.ai/mcp/gdelt/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_articles`

Search global news articles across 150+ countries and 65+ languages. GDELT monitors news media worldwide, updated every 15 minutes. Returns articles with source, date, tone score, and thumbnail image. Examples: search_articles("artificial intelligence") → AI coverage from the last 24h search_articles("oil prices", timespan="7d", sort="ToneDesc") → positive oil news from the past week search_articles("elections", source_country="france") → French election coverage Returns: List of articles with URL, title, source, language, date, and tone score.

Parameter	Type	Required	Description
`query`	string	required	Search query — keywords, exact phrases in quotes, or GDELT syntax (e.g. "climate change", "domain:bbc.com").
`timespan`	string	optional	Lookback window: "24h" (default), "7d", "2w", "3m". Max 3 months. (default: `24h`)
`max_results`	integer	optional	Max articles to return (default 25, max 250). (default: `25`)
`sort`	string	optional	Sort order: "HybridRel" (relevance, default), "DateDesc", "DateAsc", "ToneDesc", "ToneAsc". (default: `HybridRel`)
`source_country`	any	optional	Filter by source country (e.g. "US", "france", "norway"). Optional.
`source_lang`	any	optional	Filter by source language (e.g. "english", "spanish"). Optional.

curl -X POST "https://context.gnist.ai/mcp/gdelt/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_articles", "arguments": {"query": "climate change"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gdelt/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'climate change'},
            'name': 'search_articles'}},
)
print(resp.json())

`get_event_timeline`

Get media coverage volume over time — tracks how a story rises and falls. Returns a time series of article counts matching the query. Useful for detecting spikes in coverage, comparing before/after events, or monitoring ongoing stories. Examples: get_event_timeline("tariffs") → tariff coverage over the past week get_event_timeline("earthquake", timespan="30d") → earthquake coverage, monthly view get_event_timeline("bitcoin", smooth=5) → smoothed Bitcoin coverage trend Returns: Time series with date and article volume at each time step.

Parameter	Type	Required	Description
`query`	string	required	Search query — keywords or GDELT syntax.
`timespan`	string	optional	Lookback window: "7d" (default), "24h", "2w", "3m". Max 3 months. (default: `7d`)
`smooth`	integer	optional	Moving-average smoothing (0-30 time steps). 0 = no smoothing (default). (default: `0`)

curl -X POST "https://context.gnist.ai/mcp/gdelt/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_event_timeline", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gdelt/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'get_event_timeline'}},
)
print(resp.json())

`get_tone_timeline`

Get media tone/sentiment over time for a topic. Tone ranges from negative (critical/alarming) to positive (optimistic/favorable). Most news falls between -10 and +5. Tracks how public sentiment shifts around events, announcements, or crises. Examples: get_tone_timeline("Federal Reserve") → Fed sentiment over the past week get_tone_timeline("Tesla", timespan="30d") → Tesla media sentiment, monthly get_tone_timeline("war", timespan="3m", smooth=3) → smoothed conflict tone Returns: Time series with date and tone score at each time step.

Parameter	Type	Required	Description
`query`	string	required	Search query — keywords or GDELT syntax.
`timespan`	string	optional	Lookback window: "7d" (default), "24h", "2w", "3m". Max 3 months. (default: `7d`)
`smooth`	integer	optional	Moving-average smoothing (0-30 time steps). 0 = no smoothing (default). (default: `0`)

curl -X POST "https://context.gnist.ai/mcp/gdelt/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_tone_timeline", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gdelt/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'get_tone_timeline'}},
)
print(resp.json())

`get_source_country_breakdown`

Get which countries' media are covering a topic, ranked by volume. Shows where news about a topic originates from — which countries' media outlets are writing about it most. Useful for understanding regional interest and geographic spread of coverage. Examples: get_source_country_breakdown("trade war") → which countries cover trade war most get_source_country_breakdown("AI regulation", timespan="7d") → AI regulation coverage by country get_source_country_breakdown("climate summit") → which nations' media cover climate talks Returns: List of countries sorted by coverage volume (highest first).

Parameter	Type	Required	Description
`query`	string	required	Search query — keywords or GDELT syntax.
`timespan`	string	optional	Lookback window: "24h" (default), "7d", "3m". Max 3 months. (default: `24h`)

curl -X POST "https://context.gnist.ai/mcp/gdelt/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_source_country_breakdown", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gdelt/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'get_source_country_breakdown'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/gdelt/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gdelt/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_articles to find items, then get_event_timeline to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does GDELT Global Events provide?

Global event intelligence — article search, event timelines, tone analysis, and geographic coverage from 150+ countries. It exposes 5 tools: search_articles, get_event_timeline, get_tone_timeline, get_source_country_breakdown, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the GDELT Global Events API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.