Tutorial: News Intelligence

Media

Data source: GDELT 2.0 API, Hacker News (Algolia)

Overview

News Intelligence searches across 2 data sources (GDELT 2.0 API, Hacker News (Algolia)) in a single query. It deduplicates and normalizes results, saving you from building 2 separate integrations. This tutorial walks through all 7 tools with working code examples.

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-news-intelligence": {
      "url": "https://context.gnist.ai/mcp/news-intelligence/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (7)

`search_news`

Search news across GDELT (global media, 150+ countries) and Hacker News (tech community) in parallel. Queries both sources concurrently, normalizes articles into a unified format, and deduplicates by URL when the same story appears in both sources. Examples: search_news(query="artificial intelligence") search_news(query="climate change", timespan="7d", source_country="US") search_news(query="Norway oil", source_lang="Norwegian")

Parameter	Type	Required	Description
`query`	string	required	Search query for news articles.
`timespan`	string	optional	GDELT time window (e.g. '24h', '7d', '3m'). (default: `24h`)
`max_results`	integer	optional	Max articles to return. (default: `25`)
`source_country`	any	optional	Filter GDELT by source country code.
`source_lang`	any	optional	Filter GDELT by source language code.

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

import httpx

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

`get_trending_stories`

Get trending tech and startup stories from Hacker News. Returns stories sorted by engagement (points) from the specified time window. Great for monitoring what the tech community is discussing right now. Examples: get_trending_stories() get_trending_stories(hours_ago=6, min_points=50) get_trending_stories(hours_ago=168, min_points=100, max_results=10)

Parameter	Type	Required	Description
`hours_ago`	integer	optional	Lookback window in hours. (default: `24`)
`min_points`	integer	optional	Minimum points threshold. (default: `10`)
`max_results`	integer	optional	Max stories to return. (default: `25`)

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

import httpx

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

`get_news_sentiment`

Get media sentiment timeline for a topic from global news sources (GDELT). Returns tone values (-100 to +100) over time. Negative values indicate negative coverage, positive values indicate positive coverage. Examples: get_news_sentiment(query="Tesla") get_news_sentiment(query="Norway economy", timespan="3m") get_news_sentiment(query="OpenAI", timespan="30d", smooth=5)

Parameter	Type	Required	Description
`query`	string	required	Topic to analyze sentiment for.
`timespan`	string	optional	Time window (e.g. '24h', '7d', '3m'). (default: `7d`)
`smooth`	integer	optional	Smoothing factor for timeline. (default: `0`)

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

import httpx

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

`get_news_coverage`

Get media coverage volume timeline for a topic from global news sources (GDELT). Returns the volume of articles published over time, useful for detecting when a topic spikes in media attention. Examples: get_news_coverage(query="Bitcoin") get_news_coverage(query="climate summit", timespan="30d") get_news_coverage(query="election", timespan="3m", smooth=3)

Parameter	Type	Required	Description
`query`	string	required	Topic to measure coverage for.
`timespan`	string	optional	Time window (e.g. '24h', '7d', '3m'). (default: `7d`)
`smooth`	integer	optional	Smoothing factor for timeline. (default: `0`)

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

import httpx

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

`get_news_geography`

Get geographic breakdown of media coverage for a topic from GDELT. Shows which countries' media are covering a topic and their relative volume. Useful for understanding the geographic spread of news coverage. Examples: get_news_geography(query="Ukraine") get_news_geography(query="oil prices", timespan="7d") get_news_geography(query="artificial intelligence", timespan="3m")

Parameter	Type	Required	Description
`query`	string	required	Topic to analyze geographic coverage for.
`timespan`	string	optional	Time window (e.g. '24h', '7d', '3m'). (default: `24h`)

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

import httpx

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

`list_news_intelligence_sources`

List all news intelligence data sources, their coverage, and data types. Shows which news databases and community platforms are queried during news intelligence operations. Examples: list_news_intelligence_sources()

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/news-intelligence/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_news_intelligence_sources'}},
)
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/news-intelligence/" \
  -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/news-intelligence/",
    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_news to find items, then get_trending_stories 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 News Intelligence provide?

Unified news intelligence — search global media (GDELT, 150+ countries) and tech community (Hacker News) in parallel. Sentiment timelines, coverage volumes, and geographic breakdowns. It exposes 7 tools: search_news, get_trending_stories, get_news_sentiment, get_news_coverage, get_news_geography, list_news_intelligence_sources, 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 News Intelligence API return?

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

Which data sources does News Intelligence aggregate?

GDELT 2.0 API, Hacker News (Algolia). Results are deduplicated and normalized into a consistent format.

Next Steps

Interactive Playground

Try tools in your browser — no setup required.

Full Reference

Complete docs for all 7 tools.

Getting Started with News Intelligence