GDELT News Scraper — Articles, Timeline & Images API

Monitor global news coverage in real time. Scrape thousands of articles, volume trends, and image-rich stories from the GDELT Project's open API — no API key, no login, no cost.

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 from nearly every corner of the planet. This actor calls the GDELT Document 2.0 API at api.gdeltproject.org/api/v2/doc/doc, supporting three modes: articles (full news list with URL, domain, language, country, tone, and social image), timeline (hourly/daily volume intensity for trend analysis), and images (articles guaranteed to have a social preview image).

Pagination works through sliding date-window logic — each request fetches up to 250 articles from a time window, then the window slides back in time until your maxResults target is reached or the requested timespan is exhausted. This means a single run can yield thousands of unique articles across weeks or months of coverage. The actor enforces a 6-second delay between requests to respect GDELT's rate limit. Queries support full GDELT syntax including AND/OR/NOT operators, phrase matching, and field filters like sourcelang:english or sourcecountry:US.

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 is free and open — zero credentials required.
• Global coverage: 100+ languages, virtually every country, updated every 15 minutes.
• Bulk output: Hundreds to thousands of articles per run through date-window pagination.
• Three modes in one: articles, timeline trends, and image-filtered stories.
• 10 fields per article: title, URL, domain, date, language, country, image, tone, query, mode.
• 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	Detected language of the article (e.g., English, Spanish)
sourcecountry	string	Country of the publishing outlet (e.g., United States, Germany)
socialimage	string	URL of the article's Open Graph / social preview image
tone	string	GDELT tone score — positive values = positive, negative = negative (in articles mode)
query	string	The search query that produced this result
mode	string	Mode used: articles, timeline, or images

In timeline mode, records additionally contain series (e.g., Volume Intensity) and value (numeric intensity score) fields, using seendate as the timestamp bucket.

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",
  "tone": "-1.23",
  "query": "artificial intelligence",
  "mode": "articles"
}

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": 500,
  "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\" AND (floods OR wildfire) sourcelang:english sourcecountry:AU",
  "mode": "articles",
  "maxResults": 1000,
  "timespan": "3m",
  "sortBy": "datedesc"
}

Input parameters

Parameter	Type	Default	Description
query	string	artificial intelligence	GDELT query. Supports AND/OR/NOT, phrases, field filters.
mode	string	articles	articles, timeline, or images.
maxResults	integer	500	Max articles to scrape (1–10000). Ignored in timeline mode.
timespan	string	1w	How far back to search: 1d, 1w, 1m, 3m, 6m, 1y.
language	string	—	Filter by language name (e.g., English, Spanish).
country	string	—	Filter by 2-letter source country code (e.g., US, DE).
sortBy	string	datedesc	datedesc, dateasc, rel, hybridrel, socialsharecount.
proxyConfiguration	object	—	Optional Apify proxy configuration.

Full input JSON:

{
  "query": "artificial intelligence",
  "mode": "articles",
  "maxResults": 500,
  "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",
    "tone": "-2.14",
    "query": "artificial intelligence",
    "mode": "articles"
  },
  {
    "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": "",
    "tone": "1.85",
    "query": "artificial intelligence",
    "mode": "articles"
  }
]

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.
• 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.
• Longer timespans = more windows: For maxResults: 2000 over 3m, the actor will make multiple paginated requests — this is normal and expected.
• Tone values: Negative tone scores (e.g., -3.5) indicate negative news framing; positive scores indicate positive coverage. Zero = neutral.
• 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 names: Use GDELT's language names: English, Spanish, French, German, Arabic, Mandarin, Russian, Portuguese.
• Large runs: For maxResults > 1000, use a timespan of at least 3m to ensure enough date windows to fill the quota.

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": 500,
    "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: 500,
  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": 500,
    "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 is completely free and open. This actor requires no credentials from you. An Apify account is only needed to run the actor on Apify's cloud infrastructure.

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 API returns up to 250 articles per request. This actor paginates through date windows to reach maxResults (up to 10,000). Actual yield depends on coverage volume for your query and timespan — popular topics like "artificial intelligence" or "climate change" easily yield thousands of articles per month.

Why do I get zero results?

Zero results usually mean: (1) the query has no matching articles in the requested timespan, (2) a very specific multi-word query has no exact matches — try broadening it, (3) the language/country filter is too restrictive. Try removing filters or extending the timespan first.

What does the tone field mean?

GDELT assigns a "tone" score to each article based on its text. Negative values (e.g., -4.2) indicate negative framing; positive values (e.g., +2.1) indicate positive framing. The scale is roughly -10 to +10. This is useful for sentiment tracking over time.

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?

Each GDELT API request takes 1–5 seconds. The actor enforces a 6-second inter-request delay to comply with GDELT's rate limit. For 500 articles (typically 2–3 requests), expect a run time of under 2 minutes.

How does timeline mode work?

Timeline mode calls GDELT's timelinevol endpoint, which returns hourly volume intensity values for your query over the requested timespan. Each data point has a seendate timestamp and a value (relative coverage intensity). This is useful for spotting when a story breaks or peaks.

Is multilingual search supported?

Yes. GDELT indexes articles in 100+ languages. You can search across all languages (default) or filter to a specific language using the language parameter (e.g., Spanish, French, Arabic). Queries can target specific languages via the sourcelang: field filter in the query string.

How often should I run this actor?

For ongoing monitoring, schedule the actor to run every hour (with a timespan: 2h to ensure overlap) or every day (timespan: 2d). Use Apify's native deduplication or filter by seendate to avoid processing the same article twice.

What GDELT query operators are supported?

GDELT supports: AND, OR, NOT, exact phrases ("in quotes"), and field filters including sourcelang:, sourcecountry:, theme:, domain:, imageface:, and more. See the GDELT Documentation for a full list.

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 its data under an open data license. The actor queries the GDELT Document API, which is a publicly accessible, free service provided by the GDELT Project. This actor does not scrape article content — it only retrieves the metadata (title, URL, domain, date, language, image URL, tone) that GDELT itself has indexed and exposed through its API.

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.