GDELT News Scraper — Articles, Timeline & Images API

Monitor global news coverage in real time. Collect up to 250 recent articles per query, volume trends, and image-rich stories from GDELT's open Document API and official export feeds — no API key or login.

What does GDELT News Scraper do?

GDELT (Global Database of Events, Language, and Tone) monitors the world's broadcast, print, and web news in over 100 languages. This actor calls the GDELT Document 2.0 API at api.gdeltproject.org/api/v2/doc/doc, supporting three modes: articles (news list with URL, domain, optional language/country metadata, and social image), timeline, and images (records with a social preview image).

The primary request uses GDELT's native timespan and returns up to the API's hard limit of 250 recent matches. Retries rotate proxy sessions and respect the upstream rate limit. If the Document API remains throttled, unfiltered runs fall back to up to the latest four hours of GDELT's official 15-minute GKG exports instead of returning a false empty dataset. Every row identifies the path in retrievalSource; fallback rows also carry a retrievalNote with the actual snapshot count. Full GDELT field filters and exact language/country filters apply to the primary API path; the fallback performs bounded keyword/phrase/parenthesized Boolean matching against GKG title and content-derived entity/theme metadata. It deliberately excludes unrelated page-navigation links and is not used for field-filtered queries.

Who is it for?

• Journalists and media analysts tracking global coverage of a story, brand, or event over time.
• Brand reputation managers monitoring how their company or product is covered worldwide.
• Academic researchers studying media framing, sentiment trends, or geopolitical discourse.
• Data scientists and NLP engineers building news corpora for model training or topic modeling.
• Intelligence and geopolitical analysts watching for emerging narratives across regions and languages.

Use cases

• Monitor coverage of a company name or executive across 50+ countries and 30 languages.
• Build a global news feed for any topic — AI regulation, climate events, political elections.
• Track volume spikes in timeline mode to detect when a story is breaking.
• Collect image-rich articles for social media monitoring dashboards.
• Research how a scientific term (e.g., mRNA, quantum computing) is covered in non-English media.

Why use GDELT News Scraper?

• Completely keyless: GDELT's API and official exports are open — zero credentials required.
• Global coverage: 100+ languages, virtually every country, updated every 15 minutes.
• Bounded bulk output: Up to 250 recent articles per query, matching the upstream API limit.
• Three modes in one: articles, timeline trends, and image-filtered stories.
• Traceable retrieval: retrievalSource and retrievalNote make API and export-fallback semantics explicit.
• Export-ready: Download results as JSON, CSV, or Excel; connect via Google Sheets, Zapier, or Make.
• Pay-per-result pricing: Only pay for the actual number of articles scraped.

What data can you extract?

Every article record contains the following fields:

Field	Type	Description
title	string	Article headline as indexed by GDELT
url	string	Full URL of the article
domain	string	Source domain (e.g., bbc.co.uk, nytimes.com)
seendate	string	When GDELT first indexed the article (format: 20260708T124500Z)
language	string | null	Detected language when exposed by the selected GDELT feed
sourcecountry	string | null	Source country when exposed by the selected GDELT feed
socialimage	string	URL of the article's Open Graph / social preview image
query	string	The search query that produced this result
mode	string	Mode used: articles, timeline, or images
retrievalSource	string	document-api or gkg-export-fallback
retrievalNote	string | null	Fallback scope or semantic caveat, when applicable

In timeline mode, records additionally contain series and numeric value fields. Document API rows expose volume intensity; fallback rows expose a clearly labelled count of matching documents per 15-minute export snapshot.

Example output record (articles mode):

{
  "title": "OpenAI Launches New AI Reasoning Model for Enterprise",
  "url": "https://techcrunch.com/2026/07/08/openai-launches-reasoning-model/",
  "domain": "techcrunch.com",
  "seendate": "20260708T100000Z",
  "language": "English",
  "sourcecountry": "United States",
  "socialimage": "https://techcrunch.com/wp-content/uploads/2026/07/openai-og.jpg",
  "query": "artificial intelligence",
  "mode": "articles",
  "retrievalSource": "document-api",
  "retrievalNote": null
}

How to use

Option A: Search by keyword or topic

1. Open the actor and set Search Query to any keyword, phrase, or GDELT expression.
2. Choose Mode: articles to get news links, timeline for trend charts, images for visual stories.
3. Set Timespan (e.g., 1w, 1m, 3m) and Max Results.
4. Optionally filter by Language (e.g., english) or Source Country (e.g., US).
5. Click Start and download results as JSON, CSV, or Excel.

Input example (keyword search):

{
  "query": "artificial intelligence regulation",
  "mode": "articles",
  "maxResults": 250,
  "timespan": "1m",
  "language": "english",
  "country": "US",
  "sortBy": "datedesc"
}

Option B: Advanced GDELT query syntax

GDELT supports rich filtering directly in the query string. You can combine operators with field filters for precise targeting.

Input example (advanced GDELT syntax):

{
  "query": "\"climate change\" (floods OR wildfire) sourcelang:english sourcecountry:AU",
  "mode": "articles",
  "maxResults": 250,
  "timespan": "3m",
  "sortBy": "datedesc"
}

Input parameters

Parameter	Type	Default	Description
query	string	artificial intelligence	GDELT query. The primary API supports its documented query syntax; export fallback supports words, quoted phrases, parentheses, OR/AND/NOT, and minus exclusions.
mode	string	articles	articles, timeline, or images.
maxResults	integer	250	Max articles to scrape (1–250, the upstream hard limit). Ignored in timeline mode.
timespan	string	3m	Primary-API window: 1d, 3d, 1w, 2w, 1m, 3m, 6m, or 1y. The rate-limit fallback scans up to the latest four hours.
language	string	—	Lowercase source-language filter from the input list (e.g., english, spanish).
country	string	—	Filter by 2-letter source country code (e.g., US, DE).
sortBy	string	datedesc	datedesc, dateasc, tonedesc, toneasc, or hybridrel. Export fallback exactly reproduces only the two date orders.
proxyConfiguration	object	Apify automatic	Proxy configuration for the primary Document API.

Full input JSON:

{
  "query": "artificial intelligence",
  "mode": "articles",
  "maxResults": 250,
  "timespan": "1w",
  "language": "",
  "country": "",
  "sortBy": "datedesc",
  "proxyConfiguration": { "useApifyProxy": true }
}

Output example

[
  {
    "title": "EU Passes Landmark Artificial Intelligence Safety Act",
    "url": "https://www.politico.eu/article/eu-ai-safety-act-2026/",
    "domain": "politico.eu",
    "seendate": "20260708T080000Z",
    "language": "English",
    "sourcecountry": "Belgium",
    "socialimage": "https://www.politico.eu/cdn-cgi/image/width=1200/polq.eu/uploads/2026/07/ai-act.jpg",
    "query": "artificial intelligence",
    "mode": "articles",
    "retrievalSource": "document-api",
    "retrievalNote": null
  },
  {
    "title": "China Deploys AI Models for National Infrastructure Monitoring",
    "url": "https://www.globaltimes.cn/page/202607/1300001.shtml",
    "domain": "globaltimes.cn",
    "seendate": "20260708T070000Z",
    "language": "English",
    "sourcecountry": "China",
    "socialimage": "",
    "query": "artificial intelligence",
    "mode": "articles",
    "retrievalSource": "document-api",
    "retrievalNote": null
  }
]

Tips for best results

• Use quoted phrases for exact matches: "machine learning" returns only that phrase, not loose keyword matches.
• Combine filters: Add sourcelang:english sourcecountry:US to the query string to target US English news without using the separate filter fields. Field-filtered queries require the primary Document API; they are never broadened silently by the export fallback.
• Timeline mode for trends: Use mode: timeline with timespan: 1m to see hourly coverage intensity — perfect for detecting breaking news spikes.
• Images mode for visual content: Use mode: images when you need articles with guaranteed preview images for social cards or dashboards.
• Rate limiting is built in: The actor respects GDELT's 5-second rate limit automatically — do not set very low timeout values.
• Country codes: Use ISO 3166-1 alpha-2 codes (US, GB, DE, FR, IN, BR, JP, AU). Check GDELT's documentation for the full list of supported country codes.
• Language values: Choose the lowercase values exposed by the input schema, such as english, spanish, french, german, arabic, chinese, russian, or portuguese.

Integrations

• Google Sheets: Connect the actor's dataset to Google Sheets via Apify's native integration. Every run automatically populates a new sheet tab with the latest articles.
• Slack: Use Apify Webhooks to post a Slack message whenever a run completes with new results.
• Zapier / Make: Trigger downstream workflows on new GDELT data — create CRM records, send emails, or post to social media.
• Scheduled runs: Use Apify Scheduler to run the actor every hour or day and maintain a live news feed for any topic.
• Webhooks: Configure afterRun webhooks to forward data to your API, database, or analytics pipeline.

API usage

cURL:

curl -X POST \
  "https://api.apify.com/v2/acts/logiover~gdelt-news-scraper/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "artificial intelligence",
    "mode": "articles",
    "maxResults": 250,
    "timespan": "1w"
  }'

Node.js (Apify client):

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });
const run = await client.actor('logiover~gdelt-news-scraper').call({
  query: 'artificial intelligence',
  mode: 'articles',
  maxResults: 250,
  timespan: '1w',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python:

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("logiover~gdelt-news-scraper").call(run_input={
    "query": "artificial intelligence",
    "mode": "articles",
    "maxResults": 250,
    "timespan": "1w",
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["title"], item["url"])

Use with AI agents (MCP)

This actor is available as a tool in Apify's MCP (Model Context Protocol) server, making it directly callable from Claude, ChatGPT plugins, LangChain agents, and other AI pipelines. Simply configure the Apify MCP server and instruct your AI: "Use the GDELT News Scraper to find all English-language articles about electric vehicles from the past month, then summarize the top themes." The actor returns structured JSON that AI agents can immediately analyze, cluster, or summarize.

FAQ

Does this require an API key or account?

No. GDELT's Document API and official 15-minute exports are open. This actor requires no GDELT credentials. An Apify account is only needed to run it on Apify Cloud.

What is GDELT and how current is the data?

GDELT (Global Database of Events, Language, and Tone) is one of the world's largest open news monitoring databases, indexing print, broadcast, and web news across 100+ languages. The dataset is updated every 15 minutes, so articles indexed in the last hour are typically available.

How many articles can I get per run?

The GDELT Document API returns up to 250 articles for one query, and this Actor exposes that upstream cap. Actual yield depends on topic coverage. When the API is continuously throttled, the bounded official-export fallback may return fewer records because it scans up to the latest four hours rather than pretending to cover the requested API window.

Why do I get zero results?

Zero results mean the selected source completed but found no matching records in its available window. If the primary API is unavailable and the request contains exact language/country or GDELT field filters, the run fails explicitly rather than returning unfiltered or falsely healthy empty data. Broaden filters only when that still serves your use case.

Does the Actor return article sentiment/tone?

No. The Document API's artlist response does not provide a per-article tone value, so the Actor does not invent one. Timeline rows expose GDELT's coverage-volume intensity in the numeric value field; run a separate NLP/sentiment step if article tone is required.

Can I export to CSV or Excel?

Yes. On the actor's dataset page, click Export and choose CSV, Excel, JSON, or XML. You can also connect the dataset to Google Sheets automatically via the Apify integration.

How fast is the scraper?

A healthy Document API request normally takes seconds. Rate-limit retries add bounded waits; if they remain unsuccessful, the actor downloads several compact official 15-minute export snapshots in parallel. The entire path is capped by a four-minute internal budget.

How does timeline mode work?

Timeline mode first calls GDELT's timelinevol endpoint, whose value is relative coverage intensity. If that endpoint is throttled, fallback rows are explicitly labelled Matching documents (GKG export fallback) and value is a raw match count per 15-minute snapshot—not an invented intensity score.

Is multilingual search supported?

Yes on the primary Document API path: use language or GDELT's sourcelang: field. The GKG fallback does not expose reliable per-row language/source-country values, so it leaves those fields null and is not used when an exact language or country filter is requested.

How often should I run this actor?

For ongoing monitoring, schedule the actor hourly with timespan: 1d, or daily with timespan: 3d, to keep overlap within the supported input presets. Use downstream deduplication by URL and seendate when combining multiple run datasets.

What GDELT query operators are supported?

The primary API supports quoted phrases, parenthesized OR blocks, minus exclusions, and GDELT field filters including sourcelang:, sourcecountry:, theme:, and domain:. The bounded export fallback additionally accepts explicit AND/NOT while evaluating words and phrases against GDELT's indexed GKG metadata, but it does not claim field-filter equivalence. See the GDELT Documentation for the primary syntax.

Are there related scrapers on Apify?

• Logiover AI News Monitor — AI-curated multi-source news with summaries
• Logiover CT Monitor — Certificate Transparency log watcher for domain discovery
• Logiover CVE Advisory Scraper — NVD/OSV vulnerability feed with CVSS scores

Is it legal?

GDELT publishes open data feeds. The actor uses the public Document API and, during sustained throttling, GDELT's official GKG exports. It does not scrape full article text; it returns metadata GDELT indexed, with unavailable fallback fields left null.

As with any data collection, users are responsible for complying with the terms of service of downstream platforms and applicable data protection laws (GDPR, CCPA, etc.). Article URLs belong to their respective publishers; do not scrape full article text without reviewing each publisher's robots.txt and terms of service.

📝 Changelog

2026-08-01

• Completed the August 2026 full health check: verified empty/programmatic default, Console UI default, and two source-informed alternative inputs on Apify.
• Confirmed successful live execution, non-empty structured output, dataset-field/type integrity, and logical sample quality within the 5-minute quality window.
• Added a bounded official GKG-export fallback for sustained Document API throttling, with retrieval provenance and nullable feed-specific metadata in the dataset contract.
• Made fallback query evaluation honor phrases, parentheses, OR/AND/NOT and minus exclusions; excluded PAGE_LINKS navigation noise that produced unrelated matches; field-filtered requests are never broadened silently.
• Aligned sort options with the official Document API, validates title/URL/timestamp/image fields before output, and made total upstream/fallback unavailability fail explicitly instead of returning a misleading successful empty dataset.
• Upgraded adm-zip to 0.6.0 and bounded archive download, entry count, and declared expansion size before processing GDELT's network-delivered export ZIPs.

2026-08-01 — Health-check remediation

• August 2026 monthly health-check remediation is in progress; this build contains fixes verified from empty/default, Console-default, targeted live probes, or field-level semantic review.
• Fixed proxy-session identifiers and retry behavior, aligned the 250-row default with the upstream cap, removed unsupported tone/pagination claims, and added field-contract validation plus a traceable official GKG-export fallback with correct Boolean/minus matching, page-link false-positive exclusion, explicit upstream/filter failure semantics, and a patched ZIP dependency.
• The final four-input matrix verdict will be appended after post-build cloud revalidation.