# Google Trends Scraper: Compare 100 Keywords (`aaronoptimus/google-trends-scraper`) Actor

Get Google Trends data in bulk: interest over time, by country, state, metro or city, related and rising queries and topics, and Trending Now. Compare up to 100 keywords on one 0–100 scale. Paste Trends URLs. Runs finish before their timeout, no compute bills, failed terms are free.

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

## Pricing

from $1.50 / 1,000 search term with data

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 & API

Get **Google Trends** data in bulk as JSON, CSV, Excel or flat spreadsheet rows: **interest over time**, **interest by country, state, metro or city**, **related and rising queries and topics** (with *Breakout* flags), and **Trending Now** with search volume, start and end times, related searches and news. **Compare up to 100 keywords on one 0–100 scale**, look up several countries in one run, or paste **Google Trends URLs**.

You pay per keyword that returns data, from **$1.50 per 1,000** on Apify's Gold tier ($3 per 1,000 on the Free tier). Compute and proxies are included, and failed terms are free.

### ⏱️ Why it doesn't time out

Google throttles automated Trends requests hard, which is why many Trends scrapers hang, time out or come back empty. This one is built around that:

- **No browser.** It calls the same data endpoints the Google Trends website uses, so it runs on 256 MB and starts in seconds.
- **Every throttled request is retried** on a fresh session and IP with short, capped backoff. If Google keeps blocking the default proxy, all parallel sessions switch to residential proxy together, at no extra cost to you.
- **A time limit per term**, so one stubborn keyword can't stall the run. A term that still fails is listed with an error and **not charged**.
- **Runs end before their timeout.** Shortly before the run's timeout, the scraper stops starting new terms, saves everything and lists the unfinished terms in the run summary (`unfinishedTerms`). They aren't charged; run just those again.
- **Crash- and migration-safe.** Progress is saved before every charge, so a restarted or migrated run never scrapes or charges the same term twice.
- **Parallel sessions** (5 by default, up to 10): roughly 30–40 minutes per 1,000 terms with every section included.

### 🔁 Switching from Apify's Google Trends Scraper or pytrends?

#### Switching from Apify's Google Trends Scraper?

Your existing input works as it is. These input names are accepted with the same meaning:

| Apify's Google Trends Scraper | This scraper |
|---|---|
| `searchTerms` | `searchTerms` (Trends URLs can go here too) |
| `isMultiple: true` (comma = several terms) | `isMultiple`: each line like `nike, adidas` becomes one comparison of those terms. Or use `"mode": "compare"` |
| `timeRange` (`""` = past 12 months) | `timeRange`, same values, `""` accepted |
| `geo` (`""` = worldwide) | `geo`, same codes. Several at once: `US, GB, DE` |
| `startUrls` (`[{ "url": … }]`) | `startUrls`, same format |
| `category` (`""` = all) | `category`, same IDs, `""` accepted |
| `customTimeRange` (`YYYY-MM-DD YYYY-MM-DD`) | `customTimeRange`, same format |
| `maxItems` (0 = no limit) | `maxItems`: max search terms, 0 = no limit |
| `maxConcurrency`, `maxRequestRetries` | `maxConcurrency` (1–10), `maxRequestRetries` (or `maxRetries`, up to 15) |
| `viewedFrom`, `skipDebugScreen`, `pageLoadTimeoutSecs` | Not needed (no browser); ignored |
| `spreadsheetId` | Not supported: paste the terms instead (the run log says so) |

Output fields have different names: `interestOverTime_timelineData` → `interestOverTime`, `interestBySubregion` / `interestByCity` / `interestBy` → `interestByRegion` (pick the level with `regionResolution`), `relatedQueries_top` / `relatedQueries_rising` → `relatedQueries.top` / `relatedQueries.rising`, `relatedTopics_top` → `relatedTopics.top`. See [Output samples](#-output-samples).

**What's different:**

| | Apify's Google Trends Scraper | This scraper |
|---|---|---|
| Runs in the last 30 days that succeeded | 58.5% (22.9% timed out)\* | Runs stop cleanly before their timeout |
| Price model | Per dataset item, **plus platform usage** (compute at 4 GB memory by default, proxies) | Per keyword with data; compute and proxies included |
| Failed or empty terms | Charged per dataset item | Free (listed with an error) |
| Keywords on one scale | Up to 5 (Google's limit) | Up to 100 |
| Several countries per run | One `geo` per run (or one per Trends URL) | `US, GB, DE` |
| Trending Now | No | Yes, with filters and monitor mode |

\* Public run statistics shown on Apify, as observed on 2026-10-06: 13,109 of 22,415 runs succeeded and 5,134 timed out.

**All-in cost for 100 keywords** (one run, one country):

| Apify tier | Apify's Google Trends Scraper | This scraper |
|---|---|---|
| Free | $0.30 for results + platform usage | **$0.30** |
| Bronze | $0.10 + platform usage | **$0.25** |
| Silver | $0.05 + platform usage | **$0.20** |
| Gold | $0.03 + platform usage | **$0.15** |

Platform usage is billed by Apify as compute units (1 CU = 1 GB of memory for 1 hour) plus proxy traffic, at your plan's rates. At the default 4 GB, every 15 minutes of run time is 1 CU. Here, the prices above are the whole bill. Per-result prices for Apify's scraper are as listed on its Store page on 2026-10-06.

#### Switching from pytrends?

pytrends calls Google's endpoints from your own IP, so it often fails with **429 Too Many Requests** after a few dozen requests. This scraper calls the same data with session rotation, proxies and retries handled for you, and returns the same values pytrends gives you (`interest_over_time`, `interest_by_region`, `related_queries`, `related_topics`, `trending_searches`), plus comparisons of up to 100 terms on one scale. Call it from Python with the Apify client (see [API](#-api-mcp-and-ai-agents)).

### 📊 Data you get

| Data | Details |
|---|---|
| Interest over time | 0–100 search interest per minute, hour, day, week or month, depending on the time range |
| Interest by region | Countries, states/regions, US metro areas (DMA) or cities |
| Related queries | Top and rising searches, with *Breakout* flags and links |
| Related topics | Top and rising topics (entities) with their type, when Google provides them (see FAQ) |
| Comparisons | Up to 100 terms on one scale, plus which term leads in each region (up to 5 terms) |
| Trending Now | What's trending in a country or region over 4, 24 or 48 hours or 7 days: search volume, % increase, start and end time, active or ended, categories, related searches (breakdown) and news articles |
| Summary | Average, peak, peak date, latest value, % change, and a *rising / falling / stable* label per term |

Works for **Web, Image, News, YouTube and Google Shopping** search, in any country or sub-region and any language. Time ranges run from the past hour to 2004–present, including custom date ranges and all Google Trends categories.

### 💸 Pricing tiers and examples

You pay per result. Compute and proxy costs are included. Prices drop with your Apify subscription tier:

| Event | Free | Bronze | Silver | Gold | Platinum | Diamond |
|---|---|---|---|---|---|---|
| Search term with data | $0.003 | $0.0025 | $0.002 | $0.0015 | $0.0013 | $0.0012 |
| Trending Now topic | $0.001 | $0.0008 | $0.0006 | $0.0005 | $0.00045 | $0.0004 |
| Run start | $0.00005 | $0.00005 | $0.00005 | $0.00005 | $0.00005 | $0.00005 |

Per 1,000 search terms: $3.00 (Free), $2.50 (Bronze), $2.00 (Silver), $1.50 (Gold), $1.30 (Platinum), $1.20 (Diamond).

| Example | Free tier | Gold tier |
|---|---|---|
| 1 keyword | $0.003 | $0.0016 |
| 100 keywords | $0.30 | $0.15 |
| 100 keywords in 3 countries | $0.90 | $0.45 |
| 1,000 keywords | $3.00 | $1.50 |
| Trending Now, 1 country, 50 topics | $0.05 | $0.025 |
| Daily Trending Now monitor, ~20 new topics a day for 30 days | $0.60 | $0.30 |

Free: terms that fail after all retries, terms Google has too little data for (all zeros), terms that can't be put on a shared scale, and terms not started before the run's timeout. News articles on Trending Now topics are included. To cap any run, set Apify's *Maximum cost per run*: the scraper stops cleanly at the limit.

### 🚀 Quick-start presets

Compare brands across a year in the US (one 0–100 scale):

```json
{ "searchTerms": ["nike", "adidas", "puma", "new balance", "asics", "hoka", "on running"], "mode": "compare", "geo": "US", "timeRange": "today 12-m" }
```

The same terms in three countries, as spreadsheet rows:

```json
{ "searchTerms": ["air fryer", "slow cooker"], "geo": "US, GB, CA", "outputFormat": "rows" }
```

Straight from a Google Trends URL:

```json
{ "searchTerms": ["https://trends.google.com/trends/explore?q=pickleball,padel&geo=US&date=today%205-y"] }
```

US cities for one term over the past 90 days:

```json
{ "searchTerms": ["matcha"], "geo": "US", "timeRange": "today 3-m", "regionResolution": "CITY", "includeRelatedTopics": false }
```

Sports trending in the US in the past 48 hours, still active:

```json
{ "trendingNowGeos": ["US"], "trendingNowHours": "48", "trendingNowCategory": "17", "trendingNowActiveOnly": true, "trendingNowMaxItems": 100 }
```

Daily monitor (schedule it): only new trending topics and new rising queries:

```json
{ "searchTerms": ["ai agents"], "trendingNowGeos": ["US", "GB"], "onlyNew": true, "monitorStoreName": "my-trends-monitor" }
```

### 📦 Output samples

**Search term** (Separate mode, shortened):

```json
{
  "type": "keyword",
  "searchTerm": "pickleball",
  "hasData": true,
  "geo": "US",
  "timeRange": "today 12-m",
  "summary": { "average": 64, "peakValue": 100, "peakDate": "2026-04-12T00:00:00.000Z", "latestValue": 50, "changePercent": 14, "trend": "stable" },
  "interestOverTime": [{ "date": "2025-09-28T00:00:00.000Z", "formattedTime": "Sep 28 – Oct 4, 2025", "value": 49, "isPartial": false }],
  "interestByRegion": [{ "geoCode": "US-HI", "geoName": "Hawaii", "value": 100 }],
  "relatedQueries": {
    "top": [{ "query": "pickleball paddle", "value": 100, "formattedValue": "100", "isBreakout": false }],
    "rising": [{ "query": "national pickleball day", "value": 300, "formattedValue": "+300%", "isBreakout": false }]
  },
  "relatedTopics": { "top": [{ "topicTitle": "Pickleball", "topicType": "Sport", "value": 100 }], "rising": [] },
  "trendsUrl": "https://trends.google.com/trends/explore?q=pickleball&date=today+12-m&geo=US"
}
```

**Comparison** (Compare mode): one item per comparison. `interestOverTime[].values` is keyed by term, `keywords[]` holds a summary per term, and with more than 5 terms a `normalization` block names the anchor term and flags any terms whose scaling is approximate.

**Trending Now topic** (shortened):

```json
{
  "type": "trending",
  "rank": 1,
  "geo": "US",
  "title": "dodgers vs braves",
  "searchVolume": 200000,
  "approxTraffic": "200K+",
  "increasePercentage": 1000,
  "startedAt": "2026-10-06T19:00:00.000Z",
  "endedAt": null,
  "isActive": true,
  "hours": 24,
  "categories": [{ "id": 17, "name": "Sports" }],
  "breakdownTerms": ["dodgers vs braves", "braves", "braves game", "matt olson"],
  "news": [{ "title": "Burning questions facing each NLDS team ahead of tonight's Game 3s", "url": "https://www.mlb.com/news/…", "source": "MLB.com", "publishedAt": "2026-10-06T06:05:35.000Z", "picture": "https://…" }],
  "trendsUrl": "https://trends.google.com/trends/explore?q=dodgers+vs+braves&date=now+1-d&geo=US",
  "source": "trending_now"
}
```

**Flat rows** mode returns rows with `recordType` set to `summary`, `interest_over_time`, `interest_by_region`, `related_query`, `related_topic`, `trending_now` or `error`, and the same columns on every row.

The dataset has ready-made table views: **Overview**, **Interest over time**, **Flat rows** and **Trending Now**. The run summary (`OUTPUT` in the key-value store) counts terms with and without data, failures and retries.

### 🔥 Trending Now & monitoring

**Trending Now** reads the same public data as [trends.google.com/trending](https://trends.google.com/trending), with the same filters:

- **Locations:** country codes (`US`, `GB`, `JP`) or supported regions (`US-CA`, `GB-ENG`). You can also paste a Trending Now URL such as `https://trends.google.com/trending?geo=GB&hours=48&category=17&status=active`; its filters are used.
- **Window:** past 4, 24 or 48 hours, or 7 days (`trendingNowHours`).
- **Category:** Sports, Entertainment, Politics, Technology and the other Trending Now categories (`trendingNowCategory`).
- **Active only:** skip searches that have stopped trending (`trendingNowActiveOnly`).
- **Max topics per location** (`trendingNowMaxItems`, default 50, 0 = all; the US often lists 400+ topics for 24 hours and 2,000+ for 7 days).
- **News articles** per topic (`trendingNowNewsPerTopic`, 0–10, default 3, no extra charge).

If Google's Trending Now data keeps failing, the scraper falls back to the Trending Now RSS feed (about the last day, without categories) and says so in each item's `warnings`. With a category filter there's no fallback, since the feed can't be filtered: the location is reported as failed and not charged.

**Monitor mode** (`onlyNew: true`) is for scheduled runs. It returns only Trending Now topics and rising related queries that no earlier run returned, so each run is a list of what's new:

- What was returned is remembered in a named key-value store in your account (`monitorStoreName`, default `google-trends-monitor`). Use a different name per schedule to keep separate memories, or delete the store to start over.
- The first run returns everything and remembers it. Topics are remembered per location, rising queries per term, location, time range, category and search type. Entries unseen for 90 days are forgotten.
- Only new trending topics are charged. Search terms are still delivered with their full data (and charged); only their `relatedQueries.rising` list is filtered, and `monitor` on each item counts what was new.
- A run with nothing new finishes normally with an empty dataset.

### 🔌 API, MCP and AI agents

JavaScript:

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'MY_APIFY_TOKEN' });
const run = await client.actor('AaronOptimus/google-trends-scraper').call({ searchTerms: ['pickleball'], geo: 'US' });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

Python:

```python
from apify_client import ApifyClient

client = ApifyClient("MY_APIFY_TOKEN")
run = client.actor("AaronOptimus/google-trends-scraper").call(run_input={"searchTerms": ["pickleball"], "geo": "US"})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

Or one HTTP call that runs the scraper and returns the items:

```bash
curl -X POST "https://api.apify.com/v2/acts/AaronOptimus~google-trends-scraper/run-sync-get-dataset-items?token=MY_APIFY_TOKEN" \
  -H "Content-Type: application/json" -d '{"searchTerms": ["pickleball"], "geo": "US"}'
```

**AI agents and MCP:** add the scraper as a tool through Apify's MCP server (`https://mcp.apify.com`) in Claude, Cursor or any MCP client, and ask for Google Trends data in plain language. You can also schedule runs and send results to Google Sheets, Slack, Zapier, Make or webhooks with Apify integrations.

### 💡 Tips

- **Values are relative, not absolute.** 100 is the peak for that term, place and period. To put several terms on the same scale, use **Compare**.
- **Comparing more than 5 terms?** Put your most popular term first. It becomes the anchor, which gives the most precise scaling. Terms more than ~100× as popular as the anchor can't be placed on the same scale; they're marked `notComparable` and not charged. Lists longer than 100 are split into separate scales of 100.
- **Data resolution:** per-minute for the past hour or 4 hours, 8-minute steps for the past day, hourly for 7 days, daily up to ~9 months, weekly up to 5 years, monthly beyond.
- **Ambiguous words?** Pick a **category**, or use a topic ID (e.g. `/m/05zppz`, from a related-topics link) to measure the topic instead of the exact phrase.
- **Big lists:** raise *Parallel sessions* for speed and set the run timeout to a few hours for many thousands of terms. Turning off regions or related data you don't need makes runs faster.

### ❓ FAQ

**Is there a Google Trends API?** Google has an alpha Trends API with limited access. This scraper works as a Google Trends API for everyone: it reads the same public data the Google Trends website shows and returns it as JSON, CSV or Excel through Apify's API.

**Why does pytrends give me 429 errors?** Google rate-limits Trends requests per IP and session. pytrends sends them from your own IP, so after a burst of requests Google answers *429 Too Many Requests*. This scraper rotates sessions and IPs, backs off briefly and retries, and doesn't charge for terms that still fail.

**What does "Breakout" mean?** In rising related queries and topics, Google shows *Breakout* instead of a percentage when a search grew by more than 5,000%. Those entries have `isBreakout: true` and `formattedValue: "Breakout"`.

**Why are some values 0?** Google shows 0 when there isn't enough search volume for that term, place and period, and so does this scraper. A term with no data at all (or only zeros) is marked `hasData: false` and isn't charged. Comparing a small term with a very popular one can also round the small one to 0.

**Why are related topics empty?** Google often withholds related topics from automated requests while still returning related queries. The item then has empty topic lists and a `warnings` note. If the first 3 terms of a run come back without topics, the scraper stops asking for them for the rest of the run, which makes it faster. The price per term is the same.

**Why do my numbers differ slightly from the website?** Google samples its data, so repeated requests can differ by a few points. That's normal for all Trends data.

**What happens if Google blocks a request?** The scraper retries on a fresh session and IP, and switches to residential proxy if needed. If a term still fails within its time limit, it's listed with an error and **not charged**. If only regions or related searches fail, you still get the rest, plus a `warnings` note.

**What if my run is about to hit its timeout?** The scraper stops starting new terms shortly before the timeout (up to 45 seconds before it) and ends normally. The run summary lists `unfinishedTerms`; those weren't charged.

**Is it legal?** The scraper only collects publicly available, aggregated statistics. It doesn't log in, solve CAPTCHAs or collect personal data. You're responsible for using the data in line with Google's terms and your local laws.

### 🛠 Support

Found a problem or need a feature? Open an issue on the **Issues** tab. See the **Changelog** for updates.

# Changelog

This Actor's version history is a separate document: https://apify.com/aaronoptimus/google-trends-scraper/changelog.md

# Actor input Schema

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

Keywords or phrases to look up, one per line (a line like "pickleball, padel" counts as two terms, as on Google Trends). You can also paste Google Trends Explore or Trending Now URLs (their location, dates, category and search type are used as-is) or topic IDs like /m/05zppz. Each term is charged once, only if data comes back.

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

Separate: each term gets its own 0–100 scale. Compare: terms are scaled against each other (100 = the highest point of any term), up to 100 terms on one scale — see "Compare all terms on one scale".

## `compareAllOnOneScale` (type: `boolean`):

Google compares at most 5 terms at once. With this on, up to 100 terms are fetched in groups that share an anchor term and rescaled onto one 0–100 scale (bigger lists are split into scales of 100). Put your most popular term first for the best precision. Off = separate groups of 5.

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

Country or region code, e.g. US, GB, DE, or a sub-region like US-CA. Separate several with commas (US, GB, CA) to get each term for each location. Leave empty for worldwide. Use codes, not names (US, not "United States").

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

Period to look at. Ignored if a custom time range is set. An empty value (as sent by other Google Trends scrapers) means past 12 months.

## `customTimeRange` (type: `string`):

Optional. Exact dates as "YYYY-MM-DD YYYY-MM-DD", e.g. "2025-01-01 2025-12-31". Overrides Time range.

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

Which Google search to measure.

## `category` (type: `string`):

Narrow results to a topic area (helps with ambiguous terms like "jaguar").

## `customCategoryId` (type: `integer`):

Optional. Any Google Trends category ID (the number after "cat=" in a Trends URL), e.g. 276 for Restaurants. Overrides Category.

## `language` (type: `string`):

Language for related queries/topics and date labels, e.g. en-US, de, fr, es, ja.

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

Optional. Look up at most this many search terms (in the order given, URLs included); 0 = no limit. Same name and meaning as "maxItems" in Apify's Google Trends Scraper. For Trending Now, use "Max trending topics per location".

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

Items: one rich JSON record per term (best for API / code). Rows: one flat row per data point with the same columns everywhere (best for CSV, Excel, Google Sheets, BI tools).

## `includeInterestByRegion` (type: `boolean`):

Include the breakdown by country / state / metro / city.

## `regionResolution` (type: `string`):

AUTO picks countries for worldwide, states/regions for a country, and cities for a sub-region. US metro areas (DMA) work for the US only.

## `includeLowVolumeRegions` (type: `boolean`):

Also return regions with little search volume.

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

Top and rising related searches (including Breakout terms).

## `includeRelatedTopics` (type: `boolean`):

Top and rising related topics (Separate mode only). Google often withholds topics from automated requests; if the first 3 terms come back without topics, the rest of the run skips them to save time. Related queries are not affected.

## `trendingNowGeos` (type: `array`):

Optional. Country codes (e.g. US, GB) or supported regions (e.g. US-CA, GB-ENG), one per line or comma-separated, to fetch what is trending, like trends.google.com/trending: search volume, % increase, start and end time, related searches (breakdown) and news articles. Charged per trending topic delivered.

## `trendingNowHours` (type: `string`):

How far back to look, as on the website.

## `trendingNowCategory` (type: `string`):

Only topics in this category (Trending Now has its own categories, different from the Explore categories above).

## `trendingNowActiveOnly` (type: `boolean`):

Only searches that are still trending (no end time yet).

## `trendingNowMaxItems` (type: `integer`):

Most topics to return per location, in Google's order (the US often lists 400+ for 24 hours and 2,000+ for 7 days). 0 = all. Each topic is charged.

## `trendingNowNewsPerTopic` (type: `integer`):

News articles to include for each topic (0 = none, which is a little faster). No extra charge.

## `onlyNew` (type: `boolean`):

For scheduled runs: return only trending topics and rising related queries that no earlier run with the same memory store returned. The first run returns everything and remembers it. Search terms are still delivered (and charged) with their full data; only their rising queries are filtered.

## `monitorStoreName` (type: `string`):

Named key-value store in your account that remembers what was already returned. Use a different name per schedule to keep separate memories. Letters, digits and hyphens.

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

Google throttles repeated requests. Apify Proxy is recommended; sessions and IPs rotate automatically.

## `useResidentialFallback` (type: `boolean`):

If Google keeps blocking the default proxy, switch to Apify residential proxy automatically. No extra cost to you.

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

How many terms to look up at the same time, each with its own session and IP. Higher is faster for big lists.

## `maxRetries` (type: `integer`):

How many times to retry with a fresh session and IP when Google throttles a request.

## `maxSecondsPerTerm` (type: `integer`):

Stop retrying a term after this long so one stubborn keyword can't stall the run. The term is reported as failed and not charged. The run also stops starting new terms shortly before its own timeout, so it finishes cleanly instead of timing out.

## `delayBetweenRequestsSecs` (type: `integer`):

Pause between requests in each session to stay under Google’s rate limits.

## Actor input object example

```json
{
  "searchTerms": [
    "pickleball",
    "padel"
  ],
  "mode": "separate",
  "compareAllOnOneScale": true,
  "geo": "US",
  "timeRange": "today 12-m",
  "searchProperty": "web",
  "category": "0",
  "language": "en-US",
  "maxItems": 0,
  "outputFormat": "items",
  "includeInterestByRegion": true,
  "regionResolution": "AUTO",
  "includeLowVolumeRegions": false,
  "includeRelatedQueries": true,
  "includeRelatedTopics": true,
  "trendingNowGeos": [],
  "trendingNowHours": "24",
  "trendingNowCategory": "0",
  "trendingNowActiveOnly": false,
  "trendingNowMaxItems": 50,
  "trendingNowNewsPerTopic": 3,
  "onlyNew": false,
  "monitorStoreName": "google-trends-monitor",
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "useResidentialFallback": true,
  "maxConcurrency": 5,
  "maxRetries": 8,
  "maxSecondsPerTerm": 90,
  "delayBetweenRequestsSecs": 1
}
```

# Actor output Schema

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

All items: one per search term or comparison (interest over time, by region, related queries and topics), one per Trending Now topic, and error items for terms that failed (not charged). With the Flat rows output format, one row per data point.

## `overview` (type: `string`):

The Overview view of the dataset: one line per term or topic with its summary.

## `trendingNow` (type: `string`):

The Trending Now view of the dataset: search volume, increase, start and end time, categories, related searches and news.

## `runSummary` (type: `string`):

Counts of terms with and without data, failed terms, trending topics, monitor-mode statistics and network figures.

# 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": [
        "pickleball",
        "padel"
    ],
    "geo": "US",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("aaronoptimus/google-trends-scraper").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": [
        "pickleball",
        "padel",
    ],
    "geo": "US",
    "proxyConfiguration": { "useApifyProxy": True },
}

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

```

## MCP server setup

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

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/tGloSHNNpYRRFNR8I/builds/SVxE6JLkILp5W6Zxb/openapi.json