# GDELT News Search - Global News by Keyword (`staymeter-labs/gdelt-news-search`) Actor

Search news articles from 65 languages worldwide via the free GDELT DOC API. Filter by keyword, country, language, domain, tone and date; get article lists or coverage and tone timelines. No key needed.

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

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## GDELT News Search — global news by keyword, country, language and tone (free)

Search **news articles from thousands of publishers in 65 languages** and get clean JSON or CSV: title, URL, publisher domain, country, language and time seen. Filter by keyword, country, language, domain, tone and date. Also returns **coverage-volume and sentiment timelines** for any topic. Data comes from the free GDELT DOC API — no API key, no browser, no proxies.

Typical searches: *news monitoring*, *brand and competitor mentions*, *media sentiment*, *news by country*, *Google News alternative*, *news API for AI agents*.

### How to use in 3 steps

1. Enter one or more **search queries** (one per line). Use quotes for exact phrases: `"climate change"`; use OR in brackets: `(solar OR wind)`.
2. Optionally narrow by **country**, **language**, **domain**, **tone** and **time window** (`15min` to `3m`, or exact dates).
3. Click **Start**. Download the dataset as JSON, CSV or Excel, or schedule the Actor (e.g. hourly) and read it through the Apify API.

### What you get

| Field | Example |
|---|---|
| `query` | `"artificial intelligence"` (the query you entered) |
| `title` | Article headline in its original language |
| `url` | Link to the article |
| `seenDate` | `2026-10-06T08:30:00Z` — when GDELT first saw it |
| `domain` | `irishtimes.com` |
| `sourceCountry` | `Ireland` — publisher's country |
| `language` | `English` |
| `imageUrl` | Social image URL, `null` when none |

Timeline modes return `query`, `metric` (`volumePercent` or `averageTone`), `date` and `value` instead.

```json
{
  "query": "climate",
  "url": "https://www.irishtimes.com/environment/climate-crisis/2026/08/20/climate-obstruction-is-stronger-than-ever-despite-growing-need-for-action/",
  "title": "New era of climate obstruction requires pretend ...",
  "seenDate": "2026-10-06T08:30:00Z",
  "domain": "irishtimes.com",
  "language": "English",
  "sourceCountry": "Ireland",
  "imageUrl": null
}
```

### Input examples

Negative English-language news about a company from the last 7 days:

```json
{ "queries": ["\"Acme Corp\""], "timespan": "7d", "sourceLanguages": ["English"], "maxTone": -3, "maxItemsPerQuery": 100 }
```

How much of global news coverage mentions a topic, per day, for a given window:

```json
{ "queries": ["semiconductor shortage"], "mode": "volumeTimeline", "startDate": "2026-09-01", "endDate": "2026-09-30" }
```

Japanese publishers only:

```json
{ "queries": ["地震 OR 台風"], "sourceCountries": ["Japan"], "timespan": "1d" }
```

### Use cases

- Brand, competitor and executive monitoring across languages
- Media sentiment and coverage trends for a topic or country
- Feeding fresh news into AI agents, RAG pipelines and dashboards
- Research datasets of news coverage

### Limits

- GDELT returns up to **250 articles per query and time window**; for more, split the window or run several queries.
- GDELT keeps about the **last 3 months**.
- GDELT asks for one request per 5 seconds, so each query takes several seconds; a busy GDELT server can slow runs down. The Actor waits and retries automatically.
- Only metadata and links are returned, not full article text.
- Tone and country filters rely on GDELT's automatic classification.

### FAQ

**Is this allowed?** GDELT states that all its datasets are "available for unlimited and unrestricted use for any academic, commercial, or governmental use of any kind without fee" (https://www.gdeltproject.org/about.html). Please cite GDELT when you publish results.

**Do I need an API key?** No.

**Why not Google News?** This uses a different, official open source: GDELT. It is free, covers more languages and adds tone and country filters.

**What does tone mean?** An average sentiment score of the article, roughly -10 (very negative) to +10 (very positive); most articles are between -5 and +5.

**Why is a query rejected?** GDELT needs words of at least 3 characters and balanced quotes/brackets; the error text is shown in the run log.

Pricing: Free to use — you only pay Apify's standard platform usage.

# Actor input Schema

## `queries` (type: `array`):

One search per line. Words are AND-ed; use quotes for an exact phrase ("climate change") and OR in brackets ((solar OR wind)). Each query runs separately and results are tagged with it.

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

articles = list of matching articles. volumeTimeline = share of global coverage over time. toneTimeline = average tone (negative to positive) of coverage over time.

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

How far back to search, e.g. 15min, 6h, 1d, 7d, 2w, 1m, 3m (GDELT keeps about 3 months). Ignored if Start date is set.

## `startDate` (type: `string`):

Only articles seen on or after this date (YYYY-MM-DD, UTC).

## `endDate` (type: `string`):

Only articles seen on or before this date (YYYY-MM-DD, UTC). Default: now.

## `sourceCountries` (type: `array`):

Keep articles from publishers in these countries. Use country names without spaces or 2-letter FIPS codes, e.g. UnitedStates, Japan, UK, FR.

## `sourceLanguages` (type: `array`):

Keep articles in these languages, e.g. English, Japanese, Spanish.

## `domains` (type: `array`):

Only these news sites, e.g. reuters.com, nhk.or.jp.

## `minTone` (type: `integer`):

Keep articles with an average tone above this (positive = upbeat). Typical range is -10 to +10.

## `maxTone` (type: `integer`):

Keep articles with an average tone below this (negative = gloomy), e.g. -3 for negative news only.

## `sort` (type: `string`):

Applies to the articles result type.

## `maxItemsPerQuery` (type: `integer`):

GDELT returns at most 250 articles per query and time window.

## Actor input object example

```json
{
  "queries": [
    "\"artificial intelligence\""
  ],
  "mode": "articles",
  "timespan": "1d",
  "sort": "datedesc",
  "maxItemsPerQuery": 100
}
```

# Actor output Schema

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

No description

# 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 = {
    "queries": [
        "\"artificial intelligence\""
    ],
    "timespan": "1d"
};

// Run the Actor and wait for it to finish
const run = await client.actor("staymeter-labs/gdelt-news-search").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 = {
    "queries": ["\"artificial intelligence\""],
    "timespan": "1d",
}

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

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

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

```

## CLI example

```bash
echo '{
  "queries": [
    "\\"artificial intelligence\\""
  ],
  "timespan": "1d"
}' |
apify call staymeter-labs/gdelt-news-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,staymeter-labs/gdelt-news-search"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/jemFnY7R1khC2pVCo/builds/JfkMh7eJfj9Tbxjmy/openapi.json