# GDELT Global News & Event Graph Fetcher (`brunofin/gdelt-news-event-graph-fetcher`) Actor

Fetch real-time global news articles and event-graph analytics from the GDELT Project 2.0 API. Supports article list mode (per-article billing) and GKG graph mode (per-entity-event billing). No API key required.

- **URL**: https://apify.com/brunofin/gdelt-news-event-graph-fetcher.md
- **Developed by:** [Bruno Finger](https://apify.com/brunofin) (community)
- **Categories:** News
- **Stats:** 1 total users, 0 monthly users, 0.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/platform/actors/running/actors-in-store#pay-per-usage

## 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 Global News & Event Graph Fetcher

Fetch real-time global news articles and event-graph analytics from the GDELT Project 2.0 API. Supports article list mode (per-article billing) and GKG graph mode (per-entity-event billing). No API key required.

### Data Source

- **API:** GDELT Project 2.0 API (`https://api.gdeltproject.org/api/v2/doc/doc`)
- **Coverage:** Real-time global news from 65+ languages, 100+ countries
- **Authentication:** None required (keyless public API)
- **Rate Limits:** Designed for public access, generous limits

### Features

- **Article List Mode (`artlist`):** Fetch news articles with URLs, titles, domains, publication dates, languages, countries, and social images
- **Event Graph Mode (`graph`):** Fetch GKG (Global Knowledge Graph) entity/event nodes with relationships
- **Time Chart Mode (`timechart`):** Get historical time-series counts for a query
- **HTML Render Mode (`htmlrender`):** Get rendered HTML visualization
- Flexible filtering by language, domain, source country, and time windows
- Per-article or per-graph-node pay-per-event billing

### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query for GDELT (keywords, phrases, or GDELT syntax) |
| `mode` | string | No | Fetch mode: `artlist`, `graph`, `timechart`, `htmlrender` (default: `artlist`) |
| `maxRecords` | integer | No | Maximum records to return (default 100, max 250) |
| `startDatetime` | string | No | Start datetime UTC: `YYYYMMDDHHMMSS` |
| `endDatetime` | string | No | End datetime UTC: `YYYYMMDDHHMMSS` |
| `timespan` | string | No | Relative time span: `1H`, `6H`, `12H`, `24H`, `3D`, `1W`, `1M` |
| `format` | string | No | Response format: `json`, `csv`, `html` (default: `json`) |
| `lang` | string | No | Language filter (e.g., `English`, `Spanish`, `French`) |
| `domain` | string | No | Domain filter (e.g., `nytimes.com`, `bbc.com`) |
| `sourceCountry` | string | No | Source country filter (e.g., `United States`, `United Kingdom`) |

### Output Fields

| Field | Type | Description |
|-------|------|-------------|
| `url` | string | Article URL (artlist mode) |
| `title` | string | Article headline/title |
| `domain` | string | Source domain |
| `seendate` | string | When GDELT first saw the article (YYYYMMDDTHHMMSSZ) |
| `language` | string | Article language |
| `sourcecountry` | string | Source country |
| `socialimage` | string | Social media preview image URL |
| `mode` | string | Fetch mode used |
| `url_mobile` | string | Mobile-optimized URL (if available) |
| `error` | string | Error message (if any) |

### Pricing

- **Model:** Pay-per-event
- **Article Fetched:** $0.001 per article (artlist mode)
- **Graph Node Fetched:** $0.001 per graph node (graph mode)
- **Category:** NEWS / MONITORING

### Example Usage

**Article list (artlist mode):**

```json
{
  "query": "climate change",
  "mode": "artlist",
  "maxRecords": 50,
  "lang": "English",
  "timespan": "24H"
}
```

**Event graph (graph mode):**

```json
{
  "query": "election fraud",
  "mode": "graph",
  "maxRecords": 100,
  "sourceCountry": "United States"
}
```

**Time series (timechart mode):**

```json
{
  "query": "covid-19 vaccine",
  "mode": "timechart",
  "timespan": "1M"
}
```

### Local Development

```bash
cd gdelt-news-event-graph-fetcher
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
echo '{"query": "llm", "mode": "artlist", "maxRecords": 5}' > INPUT.json
.venv/bin/python -m src --input-file INPUT.json
```

### Docker

```bash
docker build -t gdelt-news-event-graph-fetcher .actor/
docker run --rm -v $(pwd)/storage:/usr/src/app/storage gdelt-news-event-graph-fetcher
```

### References

- [GDELT Project 2.0 API Documentation](https://blog.gdeltproject.org/gdelt-doc-2-0-api-debuts/)
- [GDELT API Reference](https://api.gdeltproject.org/api/v2/doc/doc)
- [GDELT Global Knowledge Graph (GKG)](http://data.gdeltproject.org/gkg/index.html)

# Actor input Schema

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

Search query for GDELT (keywords, phrases, or GDELT syntax). Examples: "llm", "climate change", "election fraud", "covid-19 vaccine".

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

GDELT API mode: 'artlist' for article list (per-article billing), 'graph' for GKG entity graph (per-node billing), 'timechart' for historical time-series counts, 'htmlrender' for rendered HTML.

## `maxRecords` (type: `integer`):

Maximum number of records to return (default 100, max 250 per request). For artlist mode, this is number of articles.

## `startDatetime` (type: `string`):

Start datetime in UTC for the query window. Format: YYYYMMDDHHMMSS (e.g., 20260816000000). Defaults to last 24 hours.

## `endDatetime` (type: `string`):

End datetime in UTC for the query window. Format: YYYYMMDDHHMMSS (e.g., 20260816235959). Defaults to now.

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

Relative time span: '1H', '6H', '12H', '24H', '3D', '1W', '1M'. Used if startDatetime/endDatetime not provided.

## `format` (type: `string`):

Response format from GDELT API. JSON is recommended for programmatic use.

## `lang` (type: `string`):

Filter by language code (e.g., 'English', 'Spanish', 'French', 'Chinese', 'Russian', 'Arabic'). Empty for all languages.

## `domain` (type: `string`):

Filter by specific domain (e.g., 'nytimes.com', 'bbc.com', 'reuters.com'). Empty for all domains.

## `sourceCountry` (type: `string`):

Filter by source country code (e.g., 'United States', 'United Kingdom', 'China', 'Russia', 'Germany'). Empty for all countries.

## Actor input object example

```json
{
  "mode": "artlist",
  "maxRecords": 100,
  "format": "json"
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("brunofin/gdelt-news-event-graph-fetcher").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("brunofin/gdelt-news-event-graph-fetcher").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 '{}' |
apify call brunofin/gdelt-news-event-graph-fetcher --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,brunofin/gdelt-news-event-graph-fetcher"
        }
    }
}

```

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/LGQoBBdR8oD2UX0gr/builds/VfunlcVrXDghRmSXW/openapi.json