# Google Trends & Breakout Signal Explorer (with MCP) (`apiagent/google-trends-mcp`) Actor

Real-time Google Trends velocity intelligence for SEO and AI Agent workflows. Discovers breakout rising keywords, analyzes 5-year seasonality timelines with 3-week smoothing, and provides publication deadline recommendations. Full Native MCP support for Cursor, Claude, and Hermes.

- **URL**: https://apify.com/apiagent/google-trends-mcp.md
- **Developed by:** [Agent Wang](https://apify.com/apiagent) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.30 / 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.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

## 🔥 Google Trends Breakout & Seasonality Explorer

> **Discover trending keywords before your competitors. Find breakout queries surging +5000%, plan content around seasonal peaks, and explore real-time hot searches — all for $0.**

***

### What This Actor Does

Input a seed keyword → Get real-time trend intelligence:

✅ **Breakout Discovery** — Find queries surging +5000% that traditional SEO tools miss\
✅ **Seasonality Analysis** — See 5-year traffic patterns to plan content timing\
✅ **Real-Time Trending** — Discover what's hot right now (4h/24h/48h/7d)\
✅ **Category Filtering** — Filter by 17 categories (Tech, Finance, Shopping, AI, etc.)\
✅ **Google Property Filter** — Search across Web, YouTube, News, Images, Shopping\
✅ **Regional Breakdown** — See interest by state/sub-region\
✅ **Peak Week Prediction** — Know exactly when traffic spikes each year\
✅ **Publishing Deadline Calculator** — Get recommended publish dates (6-week lead time)\
✅ **Global Coverage** — Works for any country: US, UK, Germany, Japan, etc.

**Cost: $0** — No API key required. Uses public Google Trends data.

***

### ⚠️ Proxy Requirements

**Cloud Execution (Apify)**: This Actor requires a proxy to avoid Google rate limits. The **Proxy Configuration** input supports:

| Option | Description | Cost |
|---|---|---|
| **Apify Proxy** (recommended) | Use Apify's built-in proxy pools | Included in Apify paid plans ($49+/mo) |
| **Custom Proxy** | Enter your own proxy URL in the Proxy Configuration | Your proxy provider's pricing |

**Local MCP Server**: No proxy needed. Works directly from your machine with Cursor, Claude Desktop, or Hermes.

#### Proxy Groups

- **RESIDENTIAL** (recommended): Real user IPs, best for Google Trends
- **DATACENTER**: Faster but more likely to be rate-limited

***

### 🚀 Quick Start

#### Option 1: Use on Apify (No Code)

1. Click **"Try for free"** above
2. Enter your seed keyword (e.g. `black friday deals`)
3. Select mode: `breakout`, `seasonality`, `both`, or `trending`
4. Click **"Run"**
5. Download results as JSON, CSV, or Excel

#### Option 2: Use as MCP Server (For AI Agents)

Connect to Cursor, Claude Desktop, or Hermes:

```json
{
  "mcpServers": {
    "google-trends": {
      "command": "python",
      "args": ["path/to/mcp_server.py"]
    }
  }
}
```

Then ask your AI Agent: *"Find breakout keywords for 'black friday' and tell me when to publish content"*

***

### 📥 Input Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `mode` | `string` | `"both"` | `"breakout"`, `"seasonality"`, `"both"`, or `"trending"` |
| `seedKeywords` | `string[]` | `["ai video generator"]` | 1-10 seed keywords (required for non-trending modes) |
| `geo` | `string` | `"us"` | Country code: `us`, `gb`, `de`, `jp`, `fr`, etc. |
| `category` | `integer` | `0` | Category filter: 0=All, 5=Tech, 18=Shopping, 7=Finance, 958=AI/ML, etc. |
| `property` | `string` | `"web"` | Google property: `web`, `youtube`, `news`, `images`, `froogle` |
| `timeframe` | `string` | `"today 12-m"` | Time range: `now 1-d`, `today 3-m`, `today 5-y`, etc. |
| `fetchRegionalData` | `boolean` | `false` | Get interest by sub-region/state |
| `limit` | `integer` | `20` | Max rising queries per seed (5-100) |
| `minGrowth` | `integer` | `50` | Minimum growth % (breakouts always included) |
| `years` | `integer` | `5` | Historical years for seasonality (1-5) |
| `leadWeeks` | `integer` | `6` | Weeks before peak to publish content |

#### Category IDs

| ID | Category | ID | Category |
|---|---|---|---|
| 0 | All Categories | 45 | Health & Medical |
| 3 | Business & Industrial | 67 | Science & Technology |
| 5 | Computers & Electronics | 958 | AI & Machine Learning |
| 7 | Finance & Investing | 12 | Food & Drink |
| 8 | Games | 14 | People & Society |
| 11 | Home & Garden | 16 | News & Media |
| 13 | Internet & Telecom | 20 | Travel & Transportation |
| 18 | Shopping & E-Commerce | 29 | Real Estate |
| 44 | Beauty & Fitness | | |

***

### 📤 Output Example

#### Breakout Results (agent\_compact mode)

```markdown
## 🔥 Breakout Report: `black friday deals` (US)

**Summary**: Found **24 rising queries** | 🔥 **8 breakouts** (+5000%)

#### 🏆 Top Breakout Queries

| # | Query | Growth | Status |
|---|---|---|---|
| 1 | `black friday deals 2026 early` | +5000% | 🔥 BREAKOUT |
| 2 | `black friday tv deals 75 inch` | +3200% | 📈 Rising |
| 3 | `black friday laptop deals under 500` | +2800% | 📈 Rising |
```

#### Trending Searches (agent\_compact mode)

```markdown
## 📈 Trending Report: US (Last 24 hours)

**Summary**: Found **45 trending queries**

#### 🔥 Top Trending Searches

| # | Query | Search Volume | Category |
|---|---|---|---|
| 1 | `nfl scores today` | 500K+ | Sports |
| 2 | `iphone 16 release date` | 200K+ | Technology |
| 3 | `tesla stock price` | 100K+ | Finance |
```

#### Seasonality Results (agent\_compact mode)

```markdown
## 📅 Seasonality Report: `black friday deals` (US)

**Peak Week**: Week 47 (November)  
**Best Publish Date**: October 15, 2026  
**Lead Time**: 6 weeks before peak  

#### 5-Year Trend Pattern

| Year | Peak Week | Peak Volume |
|---|---|---|
| 2025 | Week 47 | 100 (normalized) |
| 2024 | Week 47 | 95 |
| 2023 | Week 47 | 88 |
```

#### Regional Breakdown (detailed\_json mode)

```json
{
  "seed": "bitcoin",
  "regional": {
    "region_type": "state",
    "data": [
      {"geoCode": "US-CA", "name": "California", "value": 100},
      {"geoCode": "US-NY", "name": "New York", "value": 85},
      {"geoCode": "US-TX", "name": "Texas", "value": 72}
    ]
  }
}
```

#### Detailed JSON Output

```json
{
  "seed": "black friday deals",
  "breakout": {
    "total_found": 24,
    "breakout_count": 8,
    "queries": [
      {
        "query": "black friday deals 2026 early",
        "growth_pct": 5000,
        "status": "breakout"
      }
    ]
  },
  "seasonality": {
    "peak_week": 47,
    "recommended_publish_date": "2026-10-15",
    "lead_weeks": 6,
    "yearly_pattern": [
      {"year": 2025, "peak_week": 47, "volume_normalized": 100}
    ]
  }
}
```

***

### 🔌 MCP Integration (AI Agents)

#### Available Tools

| Tool | Description |
|---|---|
| `trends_breakout` | Discover breakout and rising queries for seed keywords |
| `trends_seasonality` | Analyze 5-year patterns and get recommended publish dates |
| `trends_trending` | Get real-time trending searches by country |

#### Example Agent Prompts

> *"Find breakout keywords for 'christmas gifts' and tell me when I should start publishing content"*

> *"Analyze seasonality for 'tax software' — when is the best time to publish my article?"*

> *"What's trending in the US right now in the Technology category?"*

> *"Compare breakout trends for 'black friday' vs 'cyber monday' in the US and UK"*

***

### ❓ FAQ

#### Q: How does this differ from Google Trends website?

**A:** Google Trends website shows you data visually. This Actor extracts the data programmatically, calculates growth percentages, identifies breakouts automatically, and provides actionable publish dates — all in structured JSON you can feed into your content pipeline or AI agent.

#### Q: What's a "breakout" keyword?

**A:** A breakout keyword is one that's experiencing explosive growth (+5000% or more). These are gold mines for content creators — you can capture traffic before competition catches up. Google Trends marks these as "Breakout" instead of showing exact percentages.

#### Q: What's the difference between "breakout" and "trending" modes?

**A:**

- **Breakout mode**: Analyzes seed keywords you provide, finds related queries with explosive growth
- **Trending mode**: Shows what's hot right now in a country (like Twitter trending topics), no seed keywords needed

#### Q: How accurate is the seasonality analysis?

**A:** Very reliable for established trends (3+ years of data). We use 5-year weekly data with noise smoothing to identify consistent patterns. New or trending topics (less than 1 year data) may show less predictable patterns.

#### Q: What does "lead weeks" mean?

**A:** It's the recommended buffer time before the traffic peak. If lead weeks = 6 and peak is November 20, you should publish by October 9. This gives Google time to index and rank your content before the surge.

#### Q: Can I use this for non-US markets?

**A:** Yes! Set the `geo` parameter to any country code: `gb` (UK), `de` (Germany), `jp` (Japan), `au` (Australia), `fr` (France), etc. Each country has different seasonal patterns.

#### Q: What categories can I filter by?

**A:** 17 categories including: Computers & Electronics (5), Shopping (18), Finance (7), AI & Machine Learning (958), Health (45), Games (8), Travel (20), and more. Set `category: 0` for all categories.

#### Q: Can I search YouTube/News/Shopping trends?

**A:** Yes! Use the `property` parameter: `web` (default), `youtube`, `news`, `images`, or `froogle` (Google Shopping).

#### Q: Is there rate limiting?

**A:** The Actor uses Apify's proxy pool automatically to avoid rate limits. For free accounts, there may be some delays during high traffic. Paid Apify accounts get priority proxy access.

#### Q: How does this work with seo-research-mcp?

**A:** Perfect pipeline! Use google-trends-mcp to find breakout keywords and timing → feed those keywords into seo-research-mcp for KGR analysis → write content targeting low-competition, high-timing-opportunity keywords.

#### Q: Can I export to CSV/Excel?

**A:** Yes! After the Actor run, go to Dataset → Export → choose CSV, JSON, Excel, or XML.

***

# Actor input Schema

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

Operation mode: 'both' (Breakout + Seasonality), 'breakout', 'seasonality', or 'trending' (real-time hot searches)

## `seedKeywords` (type: `array`):

List of seed topics/keywords (Required for 'breakout', 'seasonality', and 'both' modes)

## `geo` (type: `string`):

Two-letter ISO country code (e.g., 'US', 'GB', 'DE', 'JP', 'FR')

## `category` (type: `integer`):

Google Trends topic category ID (0=All, 5=Computers & Electronics, 18=Shopping, 7=Finance, 3=Business & Industrial, 45=Health, etc.)

## `property` (type: `string`):

Target Google search ecosystem

## `timeframe` (type: `string`):

Time range for trend calculation (e.g. 'today 12-m', 'today 3-m', 'now 1-d', 'today 5-y')

## `fetchRegionalData` (type: `boolean`):

Whether to fetch interest breakdown by sub-region / state (Adds sub-region ranking; disabled by default to minimize rate limits)

## `limit` (type: `integer`):

Maximum number of rising queries to return per seed (Breakout & Trending modes)

## `minGrowth` (type: `integer`):

Minimum percentage growth threshold (Breakouts +5000% are always preserved)

## `years` (type: `integer`):

Historical timeline range for seasonality analysis (default 5 years)

## `leadWeeks` (type: `integer`):

Number of weeks required before traffic inflection point for SEO indexing and content ranking ramp-up

## `outputFormat` (type: `string`):

Format for returned reports ('detailed\_json' for full data pipelines, 'agent\_compact' for LLM / MCP agents)

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

Proxy settings to prevent Google Trends rate limits. Use Apify Proxy (recommended) or your own custom proxy URL.

## Actor input object example

```json
{
  "mode": "both",
  "seedKeywords": [
    "ai video generator",
    "christmas gift ideas"
  ],
  "geo": "US",
  "category": 0,
  "property": "web",
  "timeframe": "today 12-m",
  "fetchRegionalData": false,
  "limit": 20,
  "minGrowth": 50,
  "years": 5,
  "leadWeeks": 6,
  "outputFormat": "detailed_json",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `trends_dataset` (type: `string`):

Full structured dataset with breakout queries, seasonality patterns, and trending searches

## `summary` (type: `string`):

High-level summary of processed seeds, breakout counts, trending queries, and Markdown report for AI agents

# 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 = {
    "seedKeywords": [
        "ai video generator",
        "christmas gift ideas"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("apiagent/google-trends-mcp").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 = { "seedKeywords": [
        "ai video generator",
        "christmas gift ideas",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("apiagent/google-trends-mcp").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 '{
  "seedKeywords": [
    "ai video generator",
    "christmas gift ideas"
  ]
}' |
apify call apiagent/google-trends-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apiagent/google-trends-mcp"
        }
    }
}

```

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/nV2ZDlu8SIsnh4uGZ/builds/DTwjiSzO4eK0m72Jf/openapi.json