# News Intelligence API — global real-time news and event search across GDELT (100k+ sources, 65+ languages), Google News and Hacker News, de-duplicated into one article schema: search, timeline, trending and top headlines

> Global news search across GDELT (+ optionally merged Google-News-RSS), de-duplicated into one unified article shape. The core 'what's the news on X' call. Filter by timespan/language/country/sort; each article carries title, url, source_domain, published_at, language, snippet, image, duplicate_count, also_reported_by[].
> ReefAPI engine `news-intel` · 11 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/news-intel/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /news-intel/v1/search — 1 credit
Global news search across GDELT (+ optionally merged Google-News-RSS), de-duplicated into one unified article shape. The core 'what's the news on X' call. Filter by timespan/language/country/sort; each article carries title, url, source_domain, published_at, language, snippet, image, duplicate_count, also_reported_by[].

**Parameters:**
- `query` (string, required) — Free-text search across global news. GDELT operators are passed through (e.g. 'tesla OR ford', '"exact phrase"', 'domainis:bbc.com', 'sourcelang:spanish', 'theme:TERROR'). Case-insensitive.
- `timespan` (string, optional, default "1d") — How far back to search (GDELT timespan). Accepts Nh/Nd/Nw/Nm or minute forms like '30min'. Note GDELT covers ~last 3 months; default 1d. [one of: 1h, 12h, 1d, 3d, 1w, 2w, 1m]
- `start` (string, optional) — Absolute window START (GDELT startdatetime). Accepts YYYYMMDD, YYYYMMDDHHMMSS, or ISO (2026-06-01 / 2026-06-01T12:00:00Z). When start AND/OR end are given they OVERRIDE the relative timespan. GDELT covers ~the last 3 months.
- `end` (string, optional) — Absolute window END (GDELT enddatetime). Same formats as start. Omit for 'up to now'. Use with start for an exact date range instead of timespan.
- `language` (string, optional) — Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages. [one of: en, es, fr, de, pt, it, ru, ar, zh, ja, tr, hi]
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.
- `sort` (enum, optional, default "datedesc") — Result ordering (GDELT sort). Ranking is GDELT's own — we add no AI re-rank. [one of: datedesc, dateasc, hybridrel, tonedesc, toneasc]
- `max` (integer, optional, default 50) — Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
- `merge_google_news` (boolean, optional, default true) — Also fetch Google-News-RSS for this query and merge+de-dup with GDELT (near-live coverage). Default true. Set false for GDELT-only.
- `dedup` (boolean, optional, default true) — Collapse the same story from many outlets (exact-url + host+path + near-duplicate title clustering). Default true. Survivors carry duplicate_count + also_reported_by[]. Set false for the raw firehose.
- `similarity` (number, optional, default 0.6) — Title near-duplicate threshold for clustering (stemmed token-set Jaccard, 0.3-1.0). Higher = stricter (fewer merges). Default 0.6 — tuned for precision 1.0 + max recall (notes/dedup_quality.json).

**Returns:** articles[] (title, url, source_domain, source_country, published_at, language, snippet, image, source, duplicate_count, also_reported_by[]), total_before_dedup, removed_duplicates, sources_used[], date_range?, freshness

**Example request body:**
```json
{
  "query": "OpenAI",
  "timespan": "2d",
  "max": 40
}
```

### POST /news-intel/v1/timeline — 1 credit
How much is X in the news over time — GDELT volume-over-time (timelinevol) for a query as [{date, value}], with peak detection (max point + average + latest).

**Parameters:**
- `query` (string, required) — Free-text search across global news. GDELT operators are passed through (e.g. 'tesla OR ford', '"exact phrase"', 'domainis:bbc.com', 'sourcelang:spanish', 'theme:TERROR'). Case-insensitive.
- `timespan` (string, optional, default "1d") — How far back to search (GDELT timespan). Accepts Nh/Nd/Nw/Nm or minute forms like '30min'. Note GDELT covers ~last 3 months; default 1d. [one of: 1h, 12h, 1d, 3d, 1w, 2w, 1m]
- `start` (string, optional) — Absolute window START (GDELT startdatetime). Accepts YYYYMMDD, YYYYMMDDHHMMSS, or ISO (2026-06-01 / 2026-06-01T12:00:00Z). When start AND/OR end are given they OVERRIDE the relative timespan. GDELT covers ~the last 3 months.
- `end` (string, optional) — Absolute window END (GDELT enddatetime). Same formats as start. Omit for 'up to now'. Use with start for an exact date range instead of timespan.
- `language` (string, optional) — Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages. [one of: en, es, fr, de, pt, it, ru, ar, zh, ja, tr, hi]
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.

**Returns:** series[] (date, value), peak{date,value}, average, latest, point_count, date_range?, query

**Example request body:**
```json
{
  "query": "earthquake",
  "timespan": "1w"
}
```

### POST /news-intel/v1/sentiment — 2 credits
Sentiment / tone analysis for a query — GDELT tonechart gives the distribution of article tone (how positive/negative coverage is) as a histogram, a count-weighted average tone, a positive/neutral/negative breakdown, and the single most-positive and most-negative representative article. Answers 'how is X being covered — favorably or critically?'. GDELT-only; honest RATE_LIMITED on the 5s throttle. (alias: tone)

**Parameters:**
- `query` (string, required) — Free-text search across global news. GDELT operators are passed through (e.g. 'tesla OR ford', '"exact phrase"', 'domainis:bbc.com', 'sourcelang:spanish', 'theme:TERROR'). Case-insensitive.
- `timespan` (string, optional, default "1d") — How far back to search (GDELT timespan). Accepts Nh/Nd/Nw/Nm or minute forms like '30min'. Note GDELT covers ~last 3 months; default 1d. [one of: 1h, 12h, 1d, 3d, 1w, 2w, 1m]
- `start` (string, optional) — Absolute window START (GDELT startdatetime). Accepts YYYYMMDD, YYYYMMDDHHMMSS, or ISO (2026-06-01 / 2026-06-01T12:00:00Z). When start AND/OR end are given they OVERRIDE the relative timespan. GDELT covers ~the last 3 months.
- `end` (string, optional) — Absolute window END (GDELT enddatetime). Same formats as start. Omit for 'up to now'. Use with start for an exact date range instead of timespan.
- `language` (string, optional) — Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages. [one of: en, es, fr, de, pt, it, ru, ar, zh, ja, tr, hi]
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.

**Returns:** average_tone, sentiment (label), total_articles, distribution (positive/neutral/negative count+pct), histogram[] (tone, count), most_positive, most_negative, date_range?, freshness

**Example request body:**
```json
{
  "query": "inflation",
  "timespan": "1w"
}
```

### POST /news-intel/v1/entities — 2 credits
Top entities for a query — the people/organizations and locations most mentioned in coverage of a topic, ranked by mention count. Organizations/people are mined from article titles; locations come from GDELT's source-country distribution. Metadata-only. Useful for 'who and where is this story about'. GDELT-only; honest throttle degrade.

**Parameters:**
- `query` (string, required) — Free-text search across global news. GDELT operators are passed through (e.g. 'tesla OR ford', '"exact phrase"', 'domainis:bbc.com', 'sourcelang:spanish', 'theme:TERROR'). Case-insensitive.
- `timespan` (string, optional, default "1d") — How far back to search (GDELT timespan). Accepts Nh/Nd/Nw/Nm or minute forms like '30min'. Note GDELT covers ~last 3 months; default 1d. [one of: 1h, 12h, 1d, 3d, 1w, 2w, 1m]
- `start` (string, optional) — Absolute window START (GDELT startdatetime). Accepts YYYYMMDD, YYYYMMDDHHMMSS, or ISO (2026-06-01 / 2026-06-01T12:00:00Z). When start AND/OR end are given they OVERRIDE the relative timespan. GDELT covers ~the last 3 months.
- `end` (string, optional) — Absolute window END (GDELT enddatetime). Same formats as start. Omit for 'up to now'. Use with start for an exact date range instead of timespan.
- `language` (string, optional) — Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages. [one of: en, es, fr, de, pt, it, ru, ar, zh, ja, tr, hi]
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.
- `max` (integer, optional, default 50) — Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).

**Returns:** entities[] (name, mentions), locations[] (name, mentions), article_count, date_range?, freshness

**Example request body:**
```json
{
  "query": "OpenAI",
  "timespan": "3d"
}
```

### POST /news-intel/v1/trending — 1 credit
What's big in the news right now — a curated multi-bucket roll-up (breaking/world/tech/business/politics/science by default, or your own queries) ranked by recent volume, each with a few representative headlines.

**Parameters:**
- `queries` (array, optional) — Optional custom topic buckets (JSON array or comma string, ≤10). Omit to use the default world roll-up (breaking/world/tech/business/politics/science).
- `timespan` (string, optional, default "1d") — How far back to search (GDELT timespan). Accepts Nh/Nd/Nw/Nm or minute forms like '30min'. Note GDELT covers ~last 3 months; default 1d. [one of: 1h, 12h, 1d, 3d, 1w, 2w, 1m]
- `language` (string, optional) — Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages. [one of: en, es, fr, de, pt, it, ru, ar, zh, ja, tr, hi]
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.
- `max` (integer, optional, default 50) — Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).

**Returns:** topics[] (topic, volume, sample_headlines[] (title, url, source_domain, published_at)), ranked_by, timespan, freshness

**Example request body:**
```json
{
  "timespan": "1d"
}
```

### POST /news-intel/v1/top_headlines — 1 credit
Editor-curated top headlines by Google-News topic section (WORLD/BUSINESS/TECHNOLOGY/…) and/or country edition. De-duplicated. The 'front page' call.

**Parameters:**
- `topic` (enum, optional) — Google-News topic section for top_headlines. Hard enum (the section feeds are a fixed set). Combine with country for a localized edition. [one of: WORLD, NATION, BUSINESS, TECHNOLOGY, ENTERTAINMENT, SPORTS, SCIENCE, HEALTH]
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.
- `max` (integer, optional, default 50) — Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
- `dedup` (boolean, optional, default true) — Collapse the same story from many outlets (exact-url + host+path + near-duplicate title clustering). Default true. Survivors carry duplicate_count + also_reported_by[]. Set false for the raw firehose.

**Returns:** articles[] (unified shape), topic, country, count, removed_duplicates, freshness

**Example request body:**
```json
{
  "topic": "TECHNOLOGY"
}
```

### POST /news-intel/v1/by_source — 1 credit
Recent articles from a specific publisher domain (reuters.com, bbc.com, …). Google-News site:<domain> is the reliable primary (near-live, ~100% on-source); GDELT domain:<domain> enriches with direct publisher URLs + tone when its 5s window is free (skipped silently otherwise — never blocks). Source-exact. merge_google_news=false → GDELT-only exact.

**Parameters:**
- `source` (string, required) — A publisher domain (e.g. reuters.com, bbc.com, nytimes.com), full URL, or host. Returns that outlet's recent articles — Google-News `site:` primary (reliable, near-live) + GDELT enrichment when available. Any domain works.
- `query` (string, optional) — Free-text search across global news. GDELT operators are passed through (e.g. 'tesla OR ford', '"exact phrase"', 'domainis:bbc.com', 'sourcelang:spanish', 'theme:TERROR'). Case-insensitive.
- `timespan` (string, optional, default "1d") — How far back to search (GDELT timespan). Accepts Nh/Nd/Nw/Nm or minute forms like '30min'. Note GDELT covers ~last 3 months; default 1d. [one of: 1h, 12h, 1d, 3d, 1w, 2w, 1m]
- `language` (string, optional) — Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages. [one of: en, es, fr, de, pt, it, ru, ar, zh, ja, tr, hi]
- `sort` (enum, optional, default "datedesc") — Result ordering (GDELT sort). Ranking is GDELT's own — we add no AI re-rank. [one of: datedesc, dateasc, hybridrel, tonedesc, toneasc]
- `max` (integer, optional, default 50) — Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
- `merge_google_news` (boolean, optional, default true) — Also fetch Google-News-RSS for this query and merge+de-dup with GDELT (near-live coverage). Default true. Set false for GDELT-only.
- `dedup` (boolean, optional, default true) — Collapse the same story from many outlets (exact-url + host+path + near-duplicate title clustering). Default true. Survivors carry duplicate_count + also_reported_by[]. Set false for the raw firehose.

**Returns:** articles[] (unified shape), source_domain, count, removed_duplicates, sources_used[], freshness

**Example request body:**
```json
{
  "source": "reuters.com",
  "timespan": "3d"
}
```

### POST /news-intel/v1/coverage — 1 credit
Full-story coverage — for a story or topic, discover which news outlets are covering it. Returns the most-covered stories first, each expanded to every outlet that carried it (outlet_count + outlets[]). Ideal for media monitoring and PR: see how widely a story was reported and by whom.

**Parameters:**
- `query` (string, required) — Free-text search across global news. GDELT operators are passed through (e.g. 'tesla OR ford', '"exact phrase"', 'domainis:bbc.com', 'sourcelang:spanish', 'theme:TERROR'). Case-insensitive.
- `timespan` (string, optional, default "1d") — How far back to search (GDELT timespan). Accepts Nh/Nd/Nw/Nm or minute forms like '30min'. Note GDELT covers ~last 3 months; default 1d. [one of: 1h, 12h, 1d, 3d, 1w, 2w, 1m]
- `start` (string, optional) — Absolute window START (GDELT startdatetime). Accepts YYYYMMDD, YYYYMMDDHHMMSS, or ISO (2026-06-01 / 2026-06-01T12:00:00Z). When start AND/OR end are given they OVERRIDE the relative timespan. GDELT covers ~the last 3 months.
- `end` (string, optional) — Absolute window END (GDELT enddatetime). Same formats as start. Omit for 'up to now'. Use with start for an exact date range instead of timespan.
- `language` (string, optional) — Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages. [one of: en, es, fr, de, pt, it, ru, ar, zh, ja, tr, hi]
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.
- `max` (integer, optional, default 50) — Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
- `similarity` (number, optional, default 0.6) — Title near-duplicate threshold for clustering (stemmed token-set Jaccard, 0.3-1.0). Higher = stricter (fewer merges). Default 0.6 — tuned for precision 1.0 + max recall (notes/dedup_quality.json).

**Returns:** stories[] (title, url, source_domain, published_at, snippet, image, outlet_count, outlets[] (source_domain, url, source)), story_count, total_articles, date_range?, freshness

**Example request body:**
```json
{
  "query": "OpenAI",
  "timespan": "3d"
}
```

### POST /news-intel/v1/sources — 0 credits
Reference directory of supported news outlets, filterable by category (e.g. TECHNOLOGY, SPORTS) and country. Also returns the topic, language and country reference lists accepted by other actions. Note: by_source accepts any publisher domain — this directory is a curated starting set, not a limit.

**Parameters:**
- `category` (string, optional) — Optional filter for the sources directory by section (WORLD/BUSINESS/TECHNOLOGY/SPORTS/ENTERTAINMENT/SCIENCE/HEALTH/NATION).
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.

**Returns:** outlets[] (domain, name, category, country), count, topics[], languages[] (code, name), countries[], note

### POST /news-intel/v1/tech — 1 credit
Hacker News tech vertical — top/new/best stories, or a full-text Algolia search. Each story: title, url, points, author, num_comments, created_at, hn_url.

**Parameters:**
- `query` (string, optional) — Optional Hacker News full-text search (Algolia). Omit to get the ranked list selected by `list` (top/new/best).
- `list` (enum, optional, default "top") — Hacker News story list when no query is given (top/new/best). With a query, Algolia full-text search is used instead. [one of: top, new, best]
- `max` (integer, optional, default 50) — Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).

**Returns:** articles[] (title, url, source_domain, published_at, snippet, points, author, num_comments, hn_url), mode, count, freshness

**Example request body:**
```json
{
  "list": "top",
  "max": 20
}
```

### POST /news-intel/v1/batch — 2 credits
Run up to 10 search queries in one call (shared concurrency, GDELT 5s-window paced). results[] preserves input order; each is a de-duped search result.

**Parameters:**
- `queries` (array, required) — Up to 10 search queries — a JSON array OR a comma/semicolon string. Each is run through `search` (GDELT, de-duped) under one shared call.
- `timespan` (string, optional, default "1d") — How far back to search (GDELT timespan). Accepts Nh/Nd/Nw/Nm or minute forms like '30min'. Note GDELT covers ~last 3 months; default 1d. [one of: 1h, 12h, 1d, 3d, 1w, 2w, 1m]
- `language` (string, optional) — Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages. [one of: en, es, fr, de, pt, it, ru, ar, zh, ja, tr, hi]
- `country` (string, optional) — Restrict to a source country (GDELT FIPS country code, e.g. US, UK, FR, IN, BR). Omit for global. For top_headlines this is the Google-News edition.
- `max` (integer, optional, default 50) — Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
- `merge_google_news` (boolean, optional, default true) — Also fetch Google-News-RSS for this query and merge+de-dup with GDELT (near-live coverage). Default true. Set false for GDELT-only.
- `dedup` (boolean, optional, default true) — Collapse the same story from many outlets (exact-url + host+path + near-duplicate title clustering). Default true. Survivors carry duplicate_count + also_reported_by[]. Set false for the raw firehose.

**Returns:** results[] (query, count, articles[], removed_duplicates), query_count, total_articles, freshness

**Example request body:**
```json
{
  "queries": "openai,tesla,bitcoin",
  "timespan": "2d",
  "max": 20
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=news-intel
- Human docs page: https://reefapi.com/docs/news-intel
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt