# GDELT News Scraper — Articles, Timeline & Images (`logiover/gdelt-news-scraper`) Actor

Scrape GDELT Project by keyword, topic, or GDELT query. Extract article titles, URLs, domains, dates, languages, countries, images, and tone for news monitoring, media analysis, and research. No API key, no login.

- **URL**: https://apify.com/logiover/gdelt-news-scraper.md
- **Developed by:** [Logiover](https://apify.com/logiover) (community)
- **Categories:** News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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):**

```json
{
  "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):**

```json
{
  "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):**

```json
{
  "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:**

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

### Output example

```json
[
  {
    "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:**

```bash
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):**

```javascript
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:**

```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](https://blog.gdeltproject.org/gdelt-doc-2-0-api-debuts/) 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.

# Actor input Schema

## `query` (type: `string`):

GDELT query string. Supports keywords, quoted phrases, OR groups, minus exclusions, and field filters like sourcelang:english or sourcecountry:US. Example: "artificial intelligence" regulation. Leave blank to use the default topic.

## `mode` (type: `string`):

articles: returns matching news articles. timeline: returns coverage volume over time. images: returns articles with social images only.

## `maxResults` (type: `integer`):

Maximum number of articles to scrape. GDELT's Document API returns at most 250 articles for one query. Ignored in timeline mode.

## `timespan` (type: `string`):

How far back the primary Document API searches. Choose one of the supported presets.

## `language` (type: `string`):

Filter by article language. Leave blank for all languages.

## `country` (type: `string`):

Filter by the country the news source is based in. Leave blank for all countries.

## `sortBy` (type: `string`):

Sort Document API articles by date, tone, or hybrid relevance. The export fallback reproduces date ascending/descending only and otherwise returns newest first.

## `proxyConfiguration` (type: `object`):

Proxy settings for the primary Document API. If that API remains throttled, the Actor reads GDELT's official 15-minute export feed directly.

## Actor input object example

```json
{
  "query": "artificial intelligence",
  "mode": "articles",
  "maxResults": 250,
  "timespan": "3m",
  "language": "",
  "country": "",
  "sortBy": "datedesc",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (type: `string`):

All records extracted by this run. Open the Dataset tab to browse, filter, and export as CSV, JSON, or Excel.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("logiover/gdelt-news-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "proxyConfiguration": { "useApifyProxy": True } }

# Run the Actor and wait for it to finish
run = client.actor("logiover/gdelt-news-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call logiover/gdelt-news-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=logiover/gdelt-news-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/mRGGCPB6OkZT3wDiQ/builds/Pmq4vly3aNyWN2pcW/openapi.json