# Swellmeter — Google Trends Scraper & API for AI Agents (`cybermax/google-trends`) Actor

Keywords in, one compact record each: Google Trends interest over time with a plain-English verdict (rising, falling, spiking, stable), peak, % change, related and rising queries, top regions. Compare up to 5 terms or get trending searches by country.

- **URL**: https://apify.com/cybermax/google-trends.md
- **Developed by:** [CyberMax](https://apify.com/cybermax) (community)
- **Categories:** SEO tools, AI, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## Swellmeter: Google Trends scraper & API for AI agents

**Keywords in, one compact answer each.** Swellmeter reads Google Trends and turns it into a single JSON record per keyword that an AI agent (or a spreadsheet) can use straight away:

- a **plain-English verdict**: `"Search interest in "claude" is rising over the past 12 months (+257% …)"`
- a **direction label**: `rising`, `falling`, `spiking`, `stable` or `no data`
- **stats**: latest, average, recent vs prior average, % change over the range, slope, peak and low (with dates), volatility
- **related queries**: top and **rising / breakout** searches
- **top regions**: countries, or states/regions when you pick a country
- the **full timeline** (date + 0–100 value), with Google's partial last point marked
- a link that opens the same view on trends.google.com

It also **compares up to 5 terms** on one scale (leader, ranking, per-keyword stats) and returns **today's trending searches** for any country, with traffic estimates and news links.

### Why this one

- **Reliable.** Each attempt alternates between Apify's own server IP and a fresh proxy session, each with its own Google cookie and exponential back-off, and anything still rate-limited gets a second pass after a cool-down, so rate limits (HTTP 429) don't fail the run. Test runs on 2026-09-23: **60 of 60 keywords and 2 of 2 trending lists succeeded, with no failed requests** (a 40-keyword batch finished in 53 s).
- **One record per keyword, not one row per data point.** It's easy to hand to an LLM and cheap in tokens (about 3 KB without the timeline).
- **Pay per answer.** $0.003 per keyword. Failed lookups and keywords with no search volume are free. No start fee.

### Input

```json
{
  "keywords": ["chatgpt", "claude", "gemini"],
  "compare": true,
  "geo": "US",
  "timeRange": "today 12-m",
  "property": "web",
  "trendingGeos": ["US", "GB"]
}
```

| Field | Default | What it does |
|---|---|---|
| `keywords` | – | Search terms. One record each (or one per comparison set). |
| `compare` | `false` | Put keywords on one 0–100 scale, in sets of up to 5 (Google's limit). Adds `leader`, `ranking` and `perKeyword` stats. |
| `geo` | worldwide | `US`, `GB`, `DE`, `IN` … or a region like `US-CA`. |
| `timeRange` | `today 12-m` | `now 1-H`, `now 4-H`, `now 1-d`, `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, `all` (2004–now). |
| `property` | `web` | `web`, `images`, `news`, `shopping`, `youtube`. |
| `category` | `0` | Google Trends category ID (e.g. 7 Finance, 45 Health). |
| `trendingGeos` | `[]` | Countries for today's trending searches (one record each). |
| `includeTimeline` | `true` | Every data point. Turn off for the smallest output. |
| `includeRelatedQueries` / `maxRelated` | `true` / 10 | Top and rising related searches. |
| `includeRegions` / `maxRegions` | `true` / 10 | Where interest is highest. |
| `maxConcurrency` | 2 | Keywords in parallel. |
| `retryCooldownSecs` | 45 | Rate-limited keywords are retried once at the end, one at a time, after this pause. |
| `directFirst` | on | Attempts alternate between a direct connection and the proxy, starting direct. Turn off to send everything through the proxy. |
| `proxyConfiguration` | Apify Proxy | Used for every other attempt. Datacenter proxy works for normal use. For hundreds of keywords per hour, use a larger datacenter pool or `RESIDENTIAL`: Google throttles individual IPs after heavy use, and a small pool can be blocked for a while. |

### Output (real record, trimmed timeline)

```json
{
 "type": "keyword",
 "keyword": "claude",
 "keywords": [
  "claude"
 ],
 "geo": "US",
 "timeRange": "today 12-m",
 "timeRangeLabel": "past 12 months",
 "property": "web",
 "category": 0,
 "resolution": "week",
 "status": "ok",
 "summaryText": "Search interest in \"claude\" is rising over the past 12 months (+257.1% last quarter of the range vs first); peak 100 on 2026-05-24, latest 58 (partial), average 53.5.",
 "dataPoints": 52,
 "latest": 58,
 "latestDate": "2026-09-20",
 "latestIsPartial": true,
 "average": 53.5,
 "recentAverage": 56.8,
 "priorAverage": 56.8,
 "recentChangePct": 0,
 "trendChangePct": 257.1,
 "slopePer10Pct": 6.9,
 "peak": {
  "value": 100,
  "date": "2026-05-24"
 },
 "low": {
  "value": 15,
  "date": "2025-09-21"
 },
 "volatility": 0.53,
 "direction": "rising",
 "relatedQueries": {
  "top": [
   {
    "query": "ai claude",
    "value": 100,
    "formattedValue": "100",
    "breakout": false
   },
   {
    "query": "claude code",
    "value": 82,
    "formattedValue": "82",
    "breakout": false
   },
   {
    "query": "anthropic claude",
    "value": 32,
    "formattedValue": "32",
    "breakout": false
   }
  ],
  "rising": [
   {
    "query": "claude cowork",
    "value": 101400,
    "formattedValue": "Breakout",
    "breakout": true
   },
   {
    "query": "claude mythos",
    "value": 52700,
    "formattedValue": "Breakout",
    "breakout": true
   },
   {
    "query": "claude fable",
    "value": 19800,
    "formattedValue": "Breakout",
    "breakout": true
   }
  ]
 },
 "regions": [
  {
   "geo": "US-DC",
   "name": "District of Columbia",
   "value": 100
  },
  {
   "geo": "US-WY",
   "name": "Wyoming",
   "value": 89
  },
  {
   "geo": "US-CA",
   "name": "California",
   "value": 84
  }
 ],
 "timeline": [
  {
   "date": "2026-09-06",
   "value": 56
  },
  {
   "date": "2026-09-13",
   "value": 56
  },
  {
   "date": "2026-09-20",
   "value": 58,
   "partial": true
  }
 ],
 "exploreUrl": "https://trends.google.com/trends/explore?date=today%2012-m&q=claude&geo=US",
 "fetchedAt": "2026-09-23T16:21:40.546Z"
}
```

Each related query also has `containsKeyword` (true when it mentions the keyword). Google's rising lists sometimes include unrelated site-wide breakouts, so filter on it when you only want on-topic queries.

A comparison record adds `leader`, `ranking` (`[{keyword, average, direction}]`), `perKeyword` (the same stats for each term), a timeline with one column per keyword, and regions with one value per keyword. A trending record has `trending: [{rank, query, approxTraffic, approxTrafficMin, startedAt, news: [{title, url, source}]}]`.

#### How the direction is decided

`trendChangePct` compares the last quarter of the range with the first quarter. It's **rising** at +20% or more with a positive slope and **falling** at −20% or less with a negative slope. It's **spiking** when the peak falls in the most recent window, is at least twice the average, and the recent window jumped at least 50% over the one before. Everything else is **stable**. Google's partial current week/day is left out of the maths but still shown as `latest`.

### Use it from an AI agent (MCP)

The Actor is callable through Apify's hosted MCP server: `https://mcp.apify.com/?tools=cybermax/google-trends` (header `Authorization: Bearer <your Apify token>`). It's also listed in the official MCP Registry. Typical agent prompts: *"Is interest in pickleball still growing in the US?"*, *"Compare Notion, Obsidian and Coda over 5 years"*, *"What's trending in the UK right now?"*.

### Pricing

| Event | Price |
|---|---|
| Keyword analyzed (each keyword in a comparison counts once) | $0.003 |
| Trending list (one country) | $0.003 |
| Failed lookups, keywords with no search volume | free |

### When not to use it

- **Absolute search volumes.** Google Trends is relative (0–100 in the chosen range and place). Use a keyword-volume tool if you need monthly searches.
- **More than 5 terms on one scale.** Google's limit. Compare in sets that share one anchor term.
- **Real-time minute-by-minute monitoring.** `now 1-H` is the finest range. Schedule runs for alerts.

### Notes

Data comes from Google Trends' public web endpoints, the same ones trends.google.com uses, called politely with retries. Values can shift slightly between runs because Google samples. Not affiliated with Google.

More from the same developer: **Boardroom Buys** (SEC insider trades), **DomainDNA** (domain tech stack & email security), **HireHeat** (company hiring signals), **SnapScout** (website screenshots), all on [apify.com/cybermax](https://apify.com/cybermax).

# Actor input Schema

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

Search terms. Each keyword returns one record (interest over time, trend verdict, related queries, regions). Turn on 'Compare' to put up to 5 keywords on the same 0–100 scale.

## `compare` (type: `boolean`):

Groups keywords into comparison sets of up to 5 (Google's limit), so their values share one scale and you get a leader and ranking. Charged per keyword.

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

Empty = worldwide. ISO country code (US, GB, DE, IN) or region (US-CA, GB-ENG).

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

Google picks the resolution: minutes/hours for short ranges, days up to 90 days, weeks up to 5 years, months for 2004–present.

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

Which Google search property to measure.

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

Optional Google Trends category (0 = all). Examples: 5 Computers & Electronics, 7 Finance, 18 Shopping, 45 Health, 71 Food & Drink.

## `trendingGeos` (type: `array`):

Optional. Country codes (US, GB, IN…). Each returns one record with today's trending searches: query, approximate traffic, start time and news links.

## `includeTimeline` (type: `boolean`):

Adds every data point (date + 0–100 value). Turn off for the smallest output: the summary stats stay.

## `includeRelatedQueries` (type: `boolean`):

Top and rising (breakout) related searches for each keyword.

## `includeRegions` (type: `boolean`):

Where interest is highest (countries, or subregions when a country is set).

## `maxRelated` (type: `integer`):

Caps top and rising lists.

## `maxRegions` (type: `integer`):

Caps the region list.

## `maxConcurrency` (type: `integer`):

Higher is faster but Google rate-limits harder. 2 is the most reliable.

## `retryCooldownSecs` (type: `integer`):

Keywords that Google rate-limited are retried once at the end of the run, one at a time, after this pause.

## `directFirst` (type: `boolean`):

On (recommended): attempts alternate between Apify's own server IP and the proxy below, starting direct. Off: every request goes through the proxy.

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

Used for every other attempt (or all attempts if the direct option is off). Google Trends rate-limits hard; each retry uses a fresh session.

## Actor input object example

```json
{
  "keywords": [
    "chatgpt",
    "claude"
  ],
  "compare": false,
  "geo": "",
  "timeRange": "today 12-m",
  "property": "web",
  "category": 0,
  "trendingGeos": [],
  "includeTimeline": true,
  "includeRelatedQueries": true,
  "includeRegions": true,
  "maxRelated": 10,
  "maxRegions": 10,
  "maxConcurrency": 2,
  "retryCooldownSecs": 45,
  "directFirst": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# 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 = {
    "keywords": [
        "chatgpt",
        "claude"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("cybermax/google-trends").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 = {
    "keywords": [
        "chatgpt",
        "claude",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("cybermax/google-trends").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 '{
  "keywords": [
    "chatgpt",
    "claude"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call cybermax/google-trends --silent --output-dataset

```

## MCP server setup

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

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/3Ea6BTaq5RcQDaDf5/builds/j8kQmLw7IYa1MgNGO/openapi.json