docs / news-intel

News Intelligence API

base /news-intel/v19 endpoints

post/news-intel/v1/search1 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[].

Parameter		Allowed / range	Description
query	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 = 1d	optional	1h · 12h · 1d · 3d · 1w · 2w · 1m	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.
language	optional	en · es · fr · de · pt · it · ru · ar · zh · ja · tr · hi	Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages.
country	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 = datedesc	optional	datedesc · dateasc · hybridrel · tonedesc · toneasc	Result ordering (GDELT sort). Ranking is GDELT's own — we add no AI re-rank.
max = 50	optional	1–250	Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
merge_google_news = true	optional	—	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 = true	optional	—	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 = 0.6	optional	0.3–1	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).

Try in playground →

post/news-intel/v1/timeline1 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).

Parameter		Allowed / range	Description
query	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 = 1d	optional	1h · 12h · 1d · 3d · 1w · 2w · 1m	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.
language	optional	en · es · fr · de · pt · it · ru · ar · zh · ja · tr · hi	Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages.
country	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.

Try in playground →

post/news-intel/v1/trending1 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.

Parameter		Allowed / range	Description
queries	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 = 1d	optional	1h · 12h · 1d · 3d · 1w · 2w · 1m	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.
language	optional	en · es · fr · de · pt · it · ru · ar · zh · ja · tr · hi	Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages.
country	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 = 50	optional	1–250	Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).

Try in playground →

post/news-intel/v1/top_headlines1 credit

Editor-curated top headlines by Google-News topic section (WORLD/BUSINESS/TECHNOLOGY/…) and/or country edition. De-duplicated. The 'front page' call.

Parameter		Allowed / range	Description
topic	optional	WORLD · NATION · BUSINESS · TECHNOLOGY · ENTERTAINMENT · SPORTS · SCIENCE · HEALTH	Google-News topic section for top_headlines. Hard enum (the section feeds are a fixed set). Combine with country for a localized edition.
country	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 = 50	optional	1–250	Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
dedup = true	optional	—	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.

Try in playground →

post/news-intel/v1/by_source1 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.

Parameter		Allowed / range	Description
source	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	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 = 1d	optional	1h · 12h · 1d · 3d · 1w · 2w · 1m	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.
language	optional	en · es · fr · de · pt · it · ru · ar · zh · ja · tr · hi	Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages.
sort = datedesc	optional	datedesc · dateasc · hybridrel · tonedesc · toneasc	Result ordering (GDELT sort). Ranking is GDELT's own — we add no AI re-rank.
max = 50	optional	1–250	Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
merge_google_news = true	optional	—	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 = true	optional	—	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.

Try in playground →

post/news-intel/v1/coverage1 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.

Parameter		Allowed / range	Description
query	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 = 1d	optional	1h · 12h · 1d · 3d · 1w · 2w · 1m	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.
language	optional	en · es · fr · de · pt · it · ru · ar · zh · ja · tr · hi	Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages.
country	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 = 50	optional	1–250	Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
similarity = 0.6	optional	0.3–1	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).

Try in playground →

post/news-intel/v1/sources1 credit

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.

Parameter		Allowed / range	Description
category	optional	—	Optional filter for the sources directory by section (WORLD/BUSINESS/TECHNOLOGY/SPORTS/ENTERTAINMENT/SCIENCE/HEALTH/NATION).
country	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.

Try in playground →

post/news-intel/v1/tech1 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.

Parameter		Allowed / range	Description
query	optional	—	Optional Hacker News full-text search (Algolia). Omit to get the ranked list selected by `list` (top/new/best).
list = top	optional	top · new · best	Hacker News story list when no query is given (top/new/best). With a query, Algolia full-text search is used instead.
max = 50	optional	1–250	Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).

Try in playground →

post/news-intel/v1/batch1 credit

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.

Parameter		Allowed / range	Description
queries	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 = 1d	optional	1h · 12h · 1d · 3d · 1w · 2w · 1m	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.
language	optional	en · es · fr · de · pt · it · ru · ar · zh · ja · tr · hi	Restrict to a source language (2-letter code → GDELT sourcelang). GDELT indexes 65+ languages; common ones listed. Omit for all languages.
country	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 = 50	optional	1–250	Max articles to fetch per source before de-dup (1-250, default 50). Larger values are clamped to 250 (GDELT ceiling).
merge_google_news = true	optional	—	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 = true	optional	—	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.

Try in playground →

Example request · search

curl -X POST https://api.reefapi.com/news-intel/v1/search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"OpenAI","timespan":"2d","max":40}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}