# Google Trends Scraper & Monitor (`yushi3/google-trends-monitor`) Actor

Google Trends data for any search term: interest over time, interest by region, and top and rising related searches, for any country, period, category or YouTube/News/Shopping. Monitor mode alerts on spikes and new rising searches.

- **URL**: https://apify.com/yushi3/google-trends-monitor.md
- **Developed by:** [Yushi Homma](https://apify.com/yushi3) (community)
- **Categories:** SEO tools, Marketing
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.30 / 1,000 search term results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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 Trends Scraper & Monitor

Get [Google Trends](https://trends.google.com) data for any search term, then be alerted when one takes off. Each term comes back as one row: **interest over time, interest by region, and the top and rising related searches**, for any country or region, period, category, and web, YouTube, News, Image or Shopping search. Run it on a schedule and it flags **spikes** and **rising searches that weren't there last time**.

- **Everything from the Explore page in one row**: the full timeline (0–100), interest by country or region, the top related searches, and the rising ones with their growth ("+250%", "Breakout").
- **Spike detection built in**: each row has the latest interest, the average, the peak and a `spikeRatio`, the latest interest divided by the average of the earlier points. `isSpike` is set when it reaches your **Spike threshold**.
- **Monitoring**: `newRisingQueries` lists the rising searches that are new since the previous run. Add a webhook to be alerted about spikes and new rising searches.
- **Compare terms** on one chart (up to 5), exactly like Google Trends' compare feature, or paste Google Trends links as they are.
- **Fast and built to keep working at volume**: 8 terms are read at once, each through its own IP, so 300 terms take about 2 minutes. Google rate-limits each IP after about 100 terms; the Actor then switches that worker to a fresh IP, using cheap datacenter IPs first and residential ones only when those are exhausted.
- **API and AI agent tool**: ask "how is interest in X trending?" in one API call, or let an AI agent call it as a tool through the Apify MCP server.

### Use cases

- Spot rising topics in your niche early: the searches marked "Breakout" or new since last week.
- Track demand for your products, brands or competitors and get alerted when one spikes.
- Pick keywords and content topics by comparing terms and checking where interest is highest.
- Feed seasonality and regional demand into forecasting, pricing or ad budgets.
- Give an AI agent a "what is trending about X?" tool.

### How to use it

1. Add **Search terms** (`pickleball`, `air fryer`), or paste Google Trends explore links, which keep their own location, period and comparison.
2. Choose a **Location** (`US`, `GB`, `US-CA`, or empty for worldwide) and a **Period** (past hour up to 2004–present, or a custom range like `2026-01-01 2026-06-30`).
3. Optionally pick a **Category**, a **Search type** (YouTube, News, Images, Shopping), or turn on **Compare the terms on one chart**.
4. For monitoring, set an **Alert webhook URL** and run the Actor on a [schedule](https://docs.apify.com/platform/schedules), for example daily. The first run is the baseline. Later runs alert on spikes and new rising searches.

### Tutorial: get a Slack message when a keyword spikes or a new search starts rising

1. In [Zapier](https://zapier.com), [Make](https://www.make.com) or [n8n](https://n8n.io), create a scenario that starts with a **webhook trigger** ("Catch Hook" in Zapier, "Custom webhook" in Make, "Webhook" node in n8n) and copy its URL.
2. Add a **Slack → Send message** step. Map `item.searchTerm`, `item.spikeRatio`, `item.newRisingQueries` and `item.trendsUrl` into the message.
3. In this Actor, add the keywords you care about, set the **Location** and a short **Period** such as **Past 30 days** or **Past 7 days**, and paste the webhook URL into **Alert webhook URL**.
4. Run it once. That run records the current rising searches as the baseline and sends no alerts.
5. Open **Schedules** in Apify Console and run the Actor daily with the same input. A term that spikes, or gets a rising search that wasn't there the day before, becomes one Slack message.

To build a history instead, connect the dataset to Google Sheets with Apify's [Google Sheets integration](https://apify.com/lukaskrivka/google-sheets) and append `searchTerm`, `latestInterest` and `scrapedAt` on every run.

### Input

```json
{
  "searchTerms": ["pickleball", "padel", "https://trends.google.com/trends/explore?q=air%20fryer&geo=GB&date=today%203-m"],
  "compareTerms": false,
  "geo": "US",
  "timeRange": "today 12-m",
  "category": 0,
  "searchProperty": "web",
  "spikeThreshold": 2,
  "alertWebhookUrl": "https://hooks.example.com/trends"
}
```

| Field | Required | Description |
| --- | --- | --- |
| `searchTerms` | yes | Keywords (up to 500) or Google Trends explore links. |
| `compareTerms` | no | Put all keywords (up to 5) on one chart so their values are relative to each other (default `false`). |
| `geo` | no | Country (`US`) or region (`US-CA`) code. Empty for worldwide (default). |
| `timeRange` | no | `now 1-H`, `now 4-H`, `now 1-d`, `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m` (default), `today 5-y`, `all`, or a custom `YYYY-MM-DD YYYY-MM-DD`. |
| `category` | no | Google Trends category ID (default `0`, all categories). |
| `searchProperty` | no | `web` (default), `youtube`, `news`, `images` or `shopping`. |
| `spikeThreshold` | no | Latest interest ÷ earlier average at which a term counts as a spike (default `2`). |
| `alertWebhookUrl` | no | From the second run on, receives a POST for every term that spikes or gets new rising searches. |
| `proxyConfiguration` | no | Leave empty for the built-in strategy (direct, then fresh datacenter and residential IPs on rate limits). |

### Output

One dataset item per search term:

```json
{
  "searchTerm": "pickleball",
  "comparedWith": [],
  "geo": "US",
  "timeRange": "today 3-m",
  "category": 0,
  "searchProperty": "web",
  "trendsUrl": "https://trends.google.com/trends/explore?q=pickleball&date=today+3-m&geo=US",
  "interestOverTime": [{"date": "2026-07-25T00:00:00.000Z", "label": "Jul 25, 2026", "value": 90, "isPartial": false}, {"date": "2026-10-25T00:00:00.000Z", "label": "Oct 25, 2026", "value": 59, "isPartial": true}],
  "averageInterest": 68.2,
  "latestInterest": 61,
  "peakInterest": 100,
  "peakDate": "2026-07-26T00:00:00.000Z",
  "spikeRatio": 0.89,
  "isSpike": false,
  "interestByRegion": [{"geoCode": "US-HI", "name": "Hawaii", "value": 100}, {"geoCode": "US-UT", "name": "Utah", "value": 93}],
  "topQueries": [{"query": "pickleball paddle", "value": 100}, {"query": "pickleball courts", "value": 90}],
  "risingQueries": [{"query": "charles barkley pickleball comments", "growth": "Breakout", "value": 6700}, {"query": "maria ford pickleball", "growth": "+4,050%", "value": 4050}],
  "newRisingQueries": ["charles barkley pickleball comments"],
  "isFirstRun": false,
  "scrapedAt": "2026-10-25T23:30:11.201Z"
}
```

- Values are Google's 0–100 scale: 100 is the peak of the chart, so values are relative within a chart, not search volumes. Compared terms share one scale.
- The latest point is often still in progress (`isPartial: true`). It is shown but left out of the averages, the peak and the spike ratio.
- `interestByRegion` is by country for worldwide charts, by state or region inside a country, and by metro or city inside a region.
- `newRisingQueries` is empty on the first run for a term (`isFirstRun: true`), which becomes the baseline.

The webhook body is `{ "actor": "google-trends-monitor", "item": { ...same fields... }, "detectedAt": "<ISO time>" }`.

### API and AI agents

Run it and get the results in one call:

```bash
curl -X POST "https://api.apify.com/v2/acts/yushi3~google-trends-monitor/run-sync-get-dataset-items" \
  -H "Authorization: Bearer <APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["pickleball"]}'
```

It returns the dataset items as a JSON array. AI agents can call the Actor as a tool through the [Apify MCP server](https://mcp.apify.com).

### Pricing

| Event | Price |
| --- | --- |
| Search term result (timeline, regions, top and rising searches) | $0.002 |
| Trend alert delivered to your webhook | $0.002 |

Proxy traffic is included. Nothing is charged for a term that fails, and failed webhook deliveries are not billed.

### Limitations

- Google Trends shows relative interest (0–100), never absolute search volumes.
- Related topics (as opposed to related searches) are not included: Google returns them empty to anonymous visitors.
- Trending Now (today's trending searches) is not included. Use this Actor to track specific terms.
- Very rare terms may have no data: they come back with an empty timeline and no regions or related searches.

### When a term fails

Every term is processed even if one fails. Failures are listed in the run's key-value store under `FAILED_TARGETS` with the reason. The run fails outright only when Google changed its data format in a way the Actor can no longer read (it is re-tested against the live site every 12 hours) or when every term failed.

### Questions and issues

Open an issue on the Actor's **Issues** tab.

# Actor input Schema

## `searchTerms` (type: `array`):

Keywords to look up (up to 500), or Google Trends explore links, which keep their own location, period and comparison.

## `compareTerms` (type: `boolean`):

Put all search terms (up to 5) on one chart, as Google Trends' compare feature does, so their interest values are relative to each other. Off: each term gets its own chart.

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

Country code (US, GB, DE…) or region (US-CA, GB-ENG). Leave empty for worldwide.

## `timeRange` (type: `string`):

Google Trends period: a preset, or a custom range written as 2026-01-01 2026-06-30.

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

Google Trends category ID, e.g. 71 for Food & Drink (0 = all categories).

## `searchProperty` (type: `string`):

Which Google search to measure.

## `spikeThreshold` (type: `number`):

A term is a spike when its latest interest is at least this many times its average over the earlier points (default 2).

## `alertWebhookUrl` (type: `string`):

Optional. From the second run on, receives a POST for each term that spikes or gets new rising searches (Slack, email or a spreadsheet via Zapier, Make or n8n).

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

Optional. Leave empty: Google is fetched directly, switching to fresh datacenter and then residential IPs whenever it rate-limits one. Set a proxy here to use it for every request instead.

## Actor input object example

```json
{
  "searchTerms": [
    "https://trends.google.com/trends/explore?q=pickleball&date=today%2012-m&geo=US"
  ],
  "compareTerms": false,
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "searchProperty": "web",
  "spikeThreshold": 2
}
```

# Actor output Schema

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

One item per search term: interest over time and by region, top and rising related searches, and spike and new-rising flags.

# 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 = {
    "searchTerms": [
        "https://trends.google.com/trends/explore?q=pickleball&date=today%2012-m&geo=US"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("yushi3/google-trends-monitor").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 = { "searchTerms": ["https://trends.google.com/trends/explore?q=pickleball&date=today%2012-m&geo=US"] }

# Run the Actor and wait for it to finish
run = client.actor("yushi3/google-trends-monitor").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 '{
  "searchTerms": [
    "https://trends.google.com/trends/explore?q=pickleball&date=today%2012-m&geo=US"
  ]
}' |
apify call yushi3/google-trends-monitor --silent --output-dataset

```

## MCP server setup

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

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/YAb2eW08jMNW4Kh2L/builds/xMZVT0HrPMHRaz0Hd/openapi.json