# Worldwide News Search by Keyword (`plotpointtech/worldwide-news-search`) Actor

- **URL**: https://apify.com/plotpointtech/worldwide-news-search.md
- **Developed by:** [Plot Point Technologies](https://apify.com/plotpointtech) (community)
- **Categories:** News, AI, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 articles

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

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

## Worldwide News Search by Keyword

Search news coverage from tens of thousands of outlets in more than 65 languages, and get each article's headline, link, outlet, outlet country, language, date, image and tone score in one clean table. Data comes from the GDELT Project, an open, free database that monitors world news media around the clock and publishes it for public and automated use. No Google News scraping, no logins.

### Who uses it

- **PR and communications teams** tracking mentions of a brand, executive or product across world media.
- **Investors and analysts** following news on companies, sectors, central banks or commodities.
- **Researchers and journalists** studying how a topic is covered by country, language or outlet.
- **Risk and security teams** monitoring news about places, suppliers or events.

### How matching works

By default the tool scans GDELT's open 15-minute news files for your time window. An article matches when your terms appear in its headline, its URL, or the people, organizations, places and topic tags GDELT extracted from the full article text. Because GDELT translates foreign-language coverage, an English search such as `"artificial intelligence"` also finds German, Spanish or Hindi articles about the topic.

Optionally, the **GDELT search API** engine first tries GDELT's own full-text search. That service limits cloud servers heavily, so when it is unavailable the run continues automatically with the news files.

### Input

| Field | What it does |
|---|---|
| Search queries | One search per line. Quotes for exact phrases (`"interest rates"`), `OR` between alternatives (`tesla OR rivian`), parentheses for groups and `-word` to exclude. |
| Time window | `6h`, `24h`, `3d`, `2w` and so on. Or set a start and end date (UTC). |
| Source countries | Outlet country, as a name without spaces (`unitedstates`, `germany`) or a two-letter FIPS code (`US`, `UK`, `GM`). |
| Source languages | `english`, `spanish`, `french`, `arabic`, `chinese` and more. |
| Only these domains / Exclude domains | Limit to or drop specific outlets, e.g. `theguardian.com`. |
| Maximum articles per query | Cap per search (default 100). |
| Sort | Newest first (default) or oldest first. |
| Remove duplicate headlines | Drop syndicated copies with the same headline. Duplicate URLs are always removed. |
| Fetch article description | Optional. Visits each article to add its meta description, first paragraphs, author and publish time. |
| Maximum days to scan | Upper limit on the window for the news-file engine (default 3, up to 31). |

### Output

`query`, `title`, `url`, `domain`, `sourceCountry`, `language`, `seenDate` (when GDELT first saw the article, UTC, 15-minute precision), `image`, `tone` (GDELT average tone, negative to positive, usually between -10 and +10), `wordCount`, `persons`, `organizations`, `locations`, and with article details on: `description`, `leadText`, `author`, `publishedTime`, `detailsError`.

### Typical use

Schedule a run every hour with a 1h or 2h window and your brand names, then send new articles to Slack, email or Google Sheets with Apify integrations.

### Notes and limits

- Newest-first searches stop as soon as enough articles are found, so they are fast. Long windows with rare terms read more files and take longer.
- Outlet country comes from GDELT's published outlet-to-country list; some aggregators are listed under the country where they are based.
- Common words also match GDELT's topic tags, which can include articles that only touch on the subject. Use exact phrases and exclusions to narrow results.
- Article details are fetched politely from public pages. Some sites refuse automated visits or are paywalled; those fields then stay empty and the article is still returned.
- Headlines and links belong to their publishers. GDELT data is free to use with attribution to the GDELT Project.

Plot Point Technologies is not affiliated with the GDELT Project or any news publisher.

# Actor input Schema

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

One search per line. Use quotes for exact phrases ("interest rates"), OR between alternatives (tesla OR rivian), and a minus sign to exclude words (-sports). Keywords must be at least 3 characters.

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

How far back to search, e.g. 6h, 24h, 3d, 2w, 1m. Ignored when a start date is set. GDELT covers about the last 3 months.

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

UTC start, YYYY-MM-DD or YYYY-MM-DDTHH:MM.

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

UTC end, YYYY-MM-DD or YYYY-MM-DDTHH:MM. Defaults to now.

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

Only outlets based in these countries. Use English country names without spaces (unitedstates, unitedkingdom, germany, india) or two-letter FIPS codes (US, UK, GM, IN). Leave empty for worldwide.

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

Only articles written in these languages, e.g. english, spanish, french, german, chinese, arabic. Leave empty for all.

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

Limit to specific outlets, e.g. reuters.com, bbc.co.uk.

## `excludeDomains` (type: `array`):

Drop articles from these outlets.

## `maxArticles` (type: `integer`):

Stop each query after this many articles.

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

Newest first or oldest first. Relevance applies only when the GDELT search API answers; otherwise newest first is used.

## `dedupeByTitle` (type: `boolean`):

Drop articles whose headline matches one already returned (syndicated copies on other sites). Duplicate URLs are always removed.

## `fetchArticleDetails` (type: `boolean`):

Visit each article page to add its meta description, first paragraphs, author and publish time. Slower; some sites refuse automated visits, in which case these fields stay empty.

## `engine` (type: `string`):

News files (default) scans GDELT's open 15-minute news files: fast and consistent, and every article includes tone, people, organizations and places. Articles match when your terms appear in the headline, the URL, or the people, organizations, places and topics GDELT detected in the article. GDELT search API tries GDELT's full-text search first, which is often rate-limited for cloud servers; when it is, the run continues with the news files automatically.

## `maxScanDays` (type: `integer`):

The news-file engine reads every 15-minute file in the window, so long windows take longer. Newest-first searches stop as soon as enough articles are found.

## Actor input object example

```json
{
  "queries": [
    "\"artificial intelligence\""
  ],
  "timespan": "1d",
  "sourceCountries": [],
  "sourceLanguages": [],
  "domains": [],
  "excludeDomains": [],
  "maxArticles": 50,
  "sort": "newest",
  "dedupeByTitle": true,
  "fetchArticleDetails": false,
  "engine": "files",
  "maxScanDays": 3
}
```

# 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\""
    ],
    "maxArticles": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("plotpointtech/worldwide-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\""],
    "maxArticles": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("plotpointtech/worldwide-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\\""
  ],
  "maxArticles": 50
}' |
apify call plotpointtech/worldwide-news-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,plotpointtech/worldwide-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/eJsawOgH8JmasFJKk/builds/ADB9RoIqAZj9SgsVg/openapi.json