# Google News Full Coverage Clusters & Publisher Timeline (`xyrelith-data/google-news-full-coverage`) Actor

Read Google News Full Coverage story clusters with every coverage group, publisher, decoded article URL, exact publish time, thumbnail, source count, top publishers and a monitored timeline of new articles.

- **URL**: https://apify.com/xyrelith-data/google-news-full-coverage.md
- **Developed by:** [Xyrelith Data](https://apify.com/xyrelith-data) (community)
- **Categories:** News, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

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

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

## Google News Full Coverage Clusters & Publisher Timeline

Read Google News the way the newsroom sees it: one story, every outlet, every coverage group,
one row per article. Paste sections, keywords or Full Coverage story links and get publisher
names, original article URLs, exact publish times, bylines, thumbnails, coverage-group labels,
intra-group positions, source counts, top publishers, publisher speed and share of voice.

This actor is built for media monitoring, PR measurement, competitive intelligence, research and
newsroom dashboards. It is not an official Google product and needs no Google account, cookies,
API key or proxy setup.

### What you get

- **Story clusters, not a flat headline list.** Each row carries the cluster headline, Story ID,
  source count, article count, first/latest article time and the top publishers in the cluster.
- **Every Full Coverage group Google serves.** `Top news`, `All coverage`, `Opinion`,
  `Posts on X`, `Personal perspective`, `In-depth`, `For context`, `Interviews`,
  `By the numbers`, plus legacy names (`From the region`, `Fact check`, `FAQ`, `Timeline`) when
  Google returns them. Each row records its group and its position inside that group.
- **Original publisher URLs.** Google News hides the article behind an opaque token; the actor
  returns the decoded publisher URL and the Google News link side by side.
- **Publisher timeline.** Publisher article counts, share of voice, the publisher's first
  article time and how many minutes after the story started that publisher joined.
- **Monitoring.** Turn on new-article tracking and each run marks which articles are new,
  when they were first seen, and how many new articles the cluster gained since the previous run.
- **Editions.** 80+ country + language editions, from US English and UK English to German,
  French, Spanish, Portuguese, Japanese, Korean, Chinese, Arabic, Hindi and more.
- **Modes.** Front page/top stories, eight topic sections, keyword searches or direct Full
  Coverage story links.

### Input

| Field | What it does |
|---|---|
| `mode` | `sections`, `keywords` or `storyUrls`. |
| `edition` | Country + language edition, e.g. `US:en`, `GB:en`, `DE:de`, `IN:hi`, `BR:pt-419`. |
| `sections` | Any of `topStories`, `us`, `world`, `business`, `technology`, `entertainment`, `sports`, `science`, `health`. |
| `keywords` | News searches. Google News operators work: quotes, `OR`, `-term`, `site:`, `intitle:`, `when:1d`, `when:7d`, `after:`, `before:`. |
| `storyUrls` | Google News Full Coverage URLs or story tokens. |
| `coverageSections` | Keep only selected coverage groups. Leave empty for all. |
| `maxStories` | Story clusters to process. |
| `maxArticlesPerStory` | Article rows per cluster. Story statistics still cover the whole cluster. |
| `maxItems` | Hard cap on dataset rows. |
| `trackNewArticles` | Mark new articles and compute the cluster's new-article count per run. |
| `resetTracking` | Forget the stored history for the clusters in this run. |
| `decodePublisherUrls` | Resolve Google News RSS links to publisher URLs in keyword mode. |

#### Examples

Top stories in the US edition, five stories, all coverage groups:

```json
{ "mode": "sections", "edition": "US:en", "sections": ["topStories"], "maxStories": 5 }
```

World and business in the UK edition, only opinion and analysis groups:

```json
{
  "mode": "sections",
  "edition": "GB:en",
  "sections": ["world", "business"],
  "coverageSections": ["Opinion", "In-depth", "For context"],
  "maxStories": 10
}
```

Keyword monitoring with new-article tracking:

```json
{
  "mode": "keywords",
  "edition": "US:en",
  "keywords": ["electric vehicles when:7d", "\"supply chain\" when:1d"],
  "maxStories": 20,
  "trackNewArticles": true
}
```

One Full Coverage story:

```json
{
  "mode": "storyUrls",
  "storyUrls": ["https://news.google.com/stories/CAAqNggKIjBDQklTSGpvSmMzUnZjbmt0TXpZd1NoRUtEd2k2NXNLd0VoRklaRFlGaXlxVTFTZ0FQAQ"]
}
```

### Defaults

| Field | Default |
|---|---|
| `mode` | `sections` |
| `edition` | `US:en` |
| `sections` | `["topStories"]` |
| `keywords` | `[]` |
| `storyUrls` | `[]` |
| `coverageSections` | `[]` |
| `maxStories` | `20` |
| `maxArticlesPerStory` | `10` |
| `maxItems` | `100` |
| `trackNewArticles` | `false` |
| `resetTracking` | `false` |
| `decodePublisherUrls` | `true` |

### Output fields

| Field | Meaning |
|---|---|
| `storyId`, `storyUrl`, `storyHeadline`, `storyImage` | The Full Coverage cluster. `storyId` is Google's edition-specific story token. |
| `clusterKey`, `clusterSource` | Stable key for monitoring and where the cluster was discovered (`storyPage`, `rssSearch`, `rssSection`). |
| `edition`, `language`, `country` | Requested edition and its parts. |
| `section`, `discoveredSections`, `keyword` | Where the story was found. |
| `sourceCount`, `articleCount` | Unique publishers and articles Google served for the cluster. |
| `firstArticleAt`, `latestArticleAt` | Earliest and latest article time in the cluster. |
| `topPublishers` | Up to five publishers with article count and share of voice. |
| `coverageSection`, `position` | The coverage group and the row's position inside it. |
| `isStoryLead` | Whether this is the first article of the cluster. |
| `publisher`, `publisherDomain`, `title`, `url`, `googleNewsUrl`, `urlResolved` | Publisher identity and both links. |
| `publishedAt`, `author`, `thumbnail` | Exact publish time, byline when Google shows one, image when available. |
| `articleId` | Stable article token used by monitoring. |
| `publisherArticleCount`, `publisherShareOfVoice`, `publisherFirstArticleAt`, `publisherDelayMinutes` | Publisher timeline inside the cluster. |
| `isNew`, `firstSeenAt`, `storyNewArticleCount` | Present when `trackNewArticles` is on. |
| `scrapedAt` | When this row was collected. |

Empty fields are omitted, never sent as `null`. A byline or thumbnail simply does not appear
when Google does not show one.

### FAQs

**Does it need cookies, a Google account or an API key?**
No. Story and section pages are public. Keyword mode uses the public Google News RSS search feed.

**Why does keyword mode sometimes return a small coverage list?**
Google's web search page blocks datacenter traffic. The public RSS search feed is the reliable
cookieless path; it returns up to 100 items and often includes a short list of other outlets on
the same story. Sections and direct story URLs return the complete Full Coverage page.

**How many articles are in a story?**
Google typically serves 7–62 articles per Full Coverage page; there is no pagination. The actor
returns all of them (subject to `maxArticlesPerStory`).

**Can I monitor publisher speed?**
Yes. `publisherDelayMinutes` is how long after the first article in the cluster that publisher's
first article appeared; `publisherShareOfVoice` is its share of the cluster's articles.

**Does monitoring require an Apify schedule?**
A schedule is the easiest way to use it. The actor stores seen article IDs in its key-value store
between runs; run it manually and the same fields still work.

**Are all Google coverage groups supported?**
The parser reads every coverage heading Google serves, so new groups appear automatically. The
legacy names from older Google News layouts are accepted in the filter and match when present.

**Which editions are supported?**
80+ country + language pairs, including the editions that use `es-419`, `pt-419`, `zh-Hant` and
`zh-Hans`. Story IDs are edition-specific; run one edition per task for consistent monitoring.

**Can I export to CSV or Excel?**
Yes. The dataset is flat one-row-per-article with repeated cluster fields, so CSV, Excel,
Google Sheets, webhooks and the Apify API all work without nested parsing.

### Notes and limits

- Google News pages are unofficial and can change. If a page changes shape the actor reports a
  warning and still returns the rows it can parse.
- The Full Coverage page is the source of truth for cluster size; keyword RSS results can be
  smaller than the full cluster.
- Publisher URLs are decoded from Google's own page data; if one cannot be decoded, the row
  keeps `googleNewsUrl` and `urlResolved: false` instead of inventing a URL.
- Respect Google's terms and the publisher's rights when storing or republishing article content.

# Actor input Schema

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

What to discover. `sections` reads Google News topic/home pages and expands each story's Full Coverage page. `keywords` reads Google News RSS search results (article/cluster-lite; Google blocks the HTML search page for datacenter IPs). `storyUrls` expands Full Coverage story URLs directly.

## `edition` (type: `string`):

Google News edition. Country and language travel together. Story IDs are edition-specific.

## `sections` (type: `array`):

Google News sections to read: topStories, us, world, business, technology, entertainment, sports, science, health. `topStories` reads the front page; the rest read topic pages. Each story is expanded to its Full Coverage page.

## `keywords` (type: `array`):

Google News RSS search queries. Supports Google News search operators such as quotes, OR, -term, site:, intitle:, when:1d, when:7d, after:, before:. Each result is emitted with the coverage links Google returns (usually 1-5 articles).

## `storyUrls` (type: `array`):

Google News Full Coverage URLs or story tokens, e.g. `https://news.google.com/stories/CAAq...`. Paste one or more.

## `coverageSections` (type: `array`):

Optional filter for Full Coverage groups: Top news, All coverage, From the region, Opinion, Fact check, FAQ, Timeline, Posts on X, Personal perspective, In-depth, For context, Interviews, By the numbers. Leave empty for all. RSS rows are always included; this filter applies to Full Coverage pages.

## `maxStories` (type: `integer`):

Maximum story clusters to process across all selected sections, keywords or URLs.

## `maxArticlesPerStory` (type: `integer`):

Maximum article rows emitted per cluster. Story statistics still describe the whole cluster Google served.

## `maxItems` (type: `integer`):

Hard cap on dataset rows.

## `trackNewArticles` (type: `boolean`):

Compare each cluster with the previous run and add `isNew`, `firstSeenAt` and `storyNewArticleCount`. State is stored in the actor's key-value store; schedule the actor to build a timeline.

## `resetTracking` (type: `boolean`):

Forget previously seen articles for the clusters processed in this run, then treat every article as new.

## `decodePublisherUrls` (type: `boolean`):

Resolve Google News RSS links to the original publisher URL in keyword mode. Full Coverage pages already expose original URLs. Disable to reduce requests when you only need Google links.

## Actor input object example

```json
{
  "mode": "sections",
  "edition": "US:en",
  "sections": [
    "topStories"
  ],
  "keywords": [],
  "storyUrls": [],
  "coverageSections": [],
  "maxStories": 1,
  "maxArticlesPerStory": 2,
  "maxItems": 2,
  "trackNewArticles": false,
  "resetTracking": false,
  "decodePublisherUrls": true
}
```

# Actor output Schema

## `articles` (type: `string`):

Dataset containing one row per article in each story cluster.

# 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 = {
    "mode": "sections",
    "edition": "US:en",
    "sections": [
        "topStories"
    ],
    "keywords": [],
    "storyUrls": [],
    "coverageSections": [],
    "maxStories": 1,
    "maxArticlesPerStory": 2,
    "maxItems": 2,
    "trackNewArticles": false,
    "resetTracking": false,
    "decodePublisherUrls": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("xyrelith-data/google-news-full-coverage").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 = {
    "mode": "sections",
    "edition": "US:en",
    "sections": ["topStories"],
    "keywords": [],
    "storyUrls": [],
    "coverageSections": [],
    "maxStories": 1,
    "maxArticlesPerStory": 2,
    "maxItems": 2,
    "trackNewArticles": False,
    "resetTracking": False,
    "decodePublisherUrls": True,
}

# Run the Actor and wait for it to finish
run = client.actor("xyrelith-data/google-news-full-coverage").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 '{
  "mode": "sections",
  "edition": "US:en",
  "sections": [
    "topStories"
  ],
  "keywords": [],
  "storyUrls": [],
  "coverageSections": [],
  "maxStories": 1,
  "maxArticlesPerStory": 2,
  "maxItems": 2,
  "trackNewArticles": false,
  "resetTracking": false,
  "decodePublisherUrls": true
}' |
apify call xyrelith-data/google-news-full-coverage --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xyrelith-data/google-news-full-coverage"
        }
    }
}
```

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/gl3hp6i9sbI9NIR6H/builds/nDx7TZqHEeij5EPx0/openapi.json
