# Google Trends Scraper & API - Bulk, Trending Now (`wrenfield-data/google-trends-scraper`) Actor

Reliable Google Trends API: interest over time, interest by region/city, related queries and topics (top + rising), and Trending Now by country. Compare up to 5 terms, batch hundreds, any geo, time range, category or YouTube/News/Shopping. Auto-retries with fresh sessions.

- **URL**: https://apify.com/wrenfield-data/google-trends-scraper.md
- **Developed by:** [Wrenfield Data](https://apify.com/wrenfield-data) (community)
- **Categories:** SEO tools, Developer tools, Marketing
- **Features:** Limited permissions
- **Stats:** 10 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.95 / 1,000 search term analyseds

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 - Reliable, Bulk, Trending Now

**Get Google Trends data at scale without 429 errors.** Scrape **interest over time**, **interest by region** (country, state, metro, city), **related queries** (top + rising, including Breakout), optional **related topics**, and **Trending Now / daily trending searches** for any country. Compare up to 5 terms, batch hundreds of keywords in one run, and pick any geo, time range, category or search property (Web, Images, News, YouTube, Google Shopping).

A reliable **Google Trends API alternative** (Google has no official public Trends API) and a maintained replacement for pytrends. Built for SEO and content research, market research, e-commerce product research, investors and data teams.

**Already using `apify/google-trends-scraper`?** Same input, all 14 fields: `searchTerms`, `isMultiple`, `timeRange`, `geo`, `viewedFrom`, `skipDebugScreen`, `startUrls` (including `{url}` / `requestsFromUrl` objects), `spreadsheetId` (public Google Sheet), `category`, `maxItems`, `customTimeRange`, `maxConcurrency`, `maxRequestRetries`, `pageLoadTimeoutSecs`. Change only the Actor ID. Success rate on our Actor was 0.97 (32/33) on Oct 19, 2026 vs Apify's 0.56 (Store stats that day). Set `outputFormat` to `apify-compatible` for one nested row per term.

- ✅ **Reliability first** - every request gets a warmed session (NID cookie), Retry-After-aware backoff on HTTP 429, a licensed DataForSEO fallback for queries Google refuses, and a second pass for anything that failed. No proxy or IP switching to get around rate limits.
- ✅ **Optional related topics** - available as an opt-in setting (off by default, see the FAQ for how they are retrieved).
- ✅ **Everything Google Trends shows**: timeline, regions, related queries, optional related topics, Trending Now with search volume, growth %, trend breakdown and news articles.
- ✅ **Two output formats**: flat rows (one row per data point - perfect for Excel, Google Sheets, BigQuery, Looker Studio) or one row per term with nested JSON (perfect for APIs and AI agents).
- ✅ **Pay per term, not per row** - a 5-year weekly timeline (260 points) costs the same as a 7-day one. Failed and no-data terms are free.
- ✅ **Fast and cheap to run**: ~1 second per term at the default concurrency on 256 MB memory.

#### Wrenfield Search Data: keyword and AI-search visibility data, priced per result

- **Keyword data:** [Keyword Search Volume](https://apify.com/wrenfield-data/keyword-search-volume) · [Keyword Difficulty](https://apify.com/wrenfield-data/keyword-difficulty-checker) · [Keyword Research](https://apify.com/wrenfield-data/keyword-research-tool) · [Autocomplete Expander](https://apify.com/wrenfield-data/google-autocomplete-keyword-expander) · **Google Trends** · [People Also Ask](https://apify.com/wrenfield-data/people-also-ask-scraper) · [Competitor Keywords](https://apify.com/wrenfield-data/competitor-keywords) · [Keyword Gap](https://apify.com/wrenfield-data/keyword-gap-report)
- **AI search visibility:** [AI Search Visibility Tracker](https://apify.com/wrenfield-data/ai-search-visibility-tracker) · [Google AI Overview Scraper](https://apify.com/wrenfield-data/google-ai-overview-scraper) · [AI Answer Scraper](https://apify.com/wrenfield-data/ai-answer-scraper) · [Agency AI Visibility Reports](https://apify.com/wrenfield-data/agency-ai-visibility-reports)
- **Site and domain SEO:** [Domain Authority & Traffic](https://apify.com/wrenfield-data/domain-authority-traffic-checker) · [Bulk PageSpeed](https://apify.com/wrenfield-data/bulk-pagespeed-checker) · [SEO Toolkit](https://apify.com/wrenfield-data/seo-toolkit) · [SEO Agency Report](https://apify.com/wrenfield-data/seo-agency-report)

### What data can you get?

| Data | Description |
|---|---|
| Interest over time | 0-100 search interest per minute / hour / day / week / month, with `isPartial` for the last, incomplete point |
| Interest by region | Countries, subregions (states), US metros (DMA) or cities with lat/lng. Comparisons return each term's share (%) per region, like the Google Trends website |
| Related queries | Top and rising searches with value, `+250%` / `Breakout`, and a link |
| Related topics (opt-in) | Top and rising Knowledge Graph topics (ID, title, type). Off by default - enable `includeRelatedTopics` |
| Trending now | Daily trending searches per country for the past 4 h / 24 h / 48 h / 7 days: approximate search volume, growth %, start/end time, active flag, categories, the queries grouped into the trend and up to 3 news articles |

### How to use

1. Add **search terms** - one per line. To **compare** terms on one scale, put up to 5 on one line separated by commas: `coffee, tea, matcha`. You can also use topic IDs like `/m/02vqfm`.
2. Choose one or more **geos** (`US`, `GB`, `US-CA`, `US-NY-501` or empty for worldwide), a **time range** (presets or custom dates) and optionally a **category** and **search property**.
3. Optionally add countries to **Trending now**.
4. Click **Start** and download the results as JSON, CSV, Excel or via the API.

Every line of search terms is scraped for every geo. For full control, use **Advanced queries** to give each query its own geo, time range, category and property.

### Input example

```json
{
    "searchTerms": ["coffee", "tea, matcha", "/m/02vqfm"],
    "geos": ["US", "GB", "WORLDWIDE"],
    "timeRange": "today 12-m",
    "category": 0,
    "property": "web",
    "includeInterestOverTime": true,
    "includeInterestByRegion": true,
    "regionResolution": "auto",
    "includeRelatedQueries": true,
    "includeRelatedTopics": false,
    "trendingGeos": ["US", "IN"],
    "trendingHours": "24",
    "maxTrendingPerGeo": 25,
    "outputFormat": "flat"
}
```

**Time ranges:** `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 - present), or custom `2024-01-01 2024-12-31`, or hourly `2026-10-01T00 2026-10-07T23` (last 7 days, UTC).

**Search properties:** `web`, `images`, `news`, `youtube`, `shopping`.

**Top-level categories:** 0 All, 3 Arts & Entertainment, 47 Autos & Vehicles, 44 Beauty & Fitness, 22 Books & Literature, 12 Business & Industrial, 5 Computers & Electronics, 7 Finance, 71 Food & Drink, 8 Games, 45 Health, 65 Hobbies & Leisure, 11 Home & Garden, 13 Internet & Telecom, 958 Jobs & Education, 19 Law & Government, 16 News, 299 Online Communities, 14 People & Society, 66 Pets & Animals, 29 Real Estate, 533 Reference, 174 Science, 18 Shopping, 20 Sports, 67 Travel. Any Google Trends sub-category ID works too (it's the `cat=` value in a Google Trends URL).

**Advanced queries example:**

```json
[
    { "terms": "nike, adidas", "geo": "DE", "timeRange": "today 5-y", "property": "youtube" },
    { "terms": "air fryer", "geo": "US-TX", "timeRange": "2024-11-01 2024-12-31", "category": 18 }
]
```

### Output examples

**Flat format** (default) - every row has a `type`. Use the dataset views *Interest over time*, *Interest by region*, *Related queries*, *Related topics* (when enabled) and *Trending now*, or filter on `type`.

```json
{"type": "interest_over_time", "searchTerm": "coffee", "comparedWith": [], "geo": "US", "timeRange": "today 12-m", "period": "2025-10-08 2026-10-08", "category": 0, "property": "web", "date": "2025-10-05", "timestamp": 1759622400, "formattedTime": "Oct 5 – 11, 2025", "value": 62, "hasData": true, "isPartial": false, "resolution": "WEEK", "exploreUrl": "https://trends.google.com/trends/explore?q=coffee&date=today%2012-m&geo=US"}
{"type": "interest_by_region", "searchTerm": "coffee", "geo": "US", "rank": 1, "geoCode": "US-WY", "geoName": "Wyoming", "value": 100, "valueType": "interest", "resolution": "REGION"}
{"type": "related_query", "searchTerm": "coffee", "geo": "US", "rankType": "top", "rank": 1, "query": "coffee near me", "value": 100, "formattedValue": "100", "isBreakout": false, "link": "https://trends.google.com/trends/explore?q=coffee+near+me&date=today+12-m&geo=US"}
{"type": "related_topic", "searchTerm": "coffee", "geo": "US", "rankType": "top", "rank": 1, "topicId": "/m/02vqfm", "topicTitle": "Coffee", "topicType": "Beverage", "value": 100, "formattedValue": "100", "isBreakout": false}
```

**Trending now row:**

```json
{
    "type": "trending_now", "geo": "US", "rank": 1, "searchTerm": "susan dell",
    "searchVolume": 200000, "searchVolumeFormatted": "200K+", "increasePercentage": 1000,
    "startedAt": "2026-10-07T17:10:00Z", "endedAt": null, "isActive": true,
    "categories": ["Law and Government"],
    "trendBreakdown": ["susan dell", "trump accounts", "michael dell", "trump account for kids"],
    "newsArticles": [{"title": "Michael Dell defends Trump Accounts' shift to individual company stocks", "url": "https://finance.yahoo.com/...", "source": "Yahoo Finance", "publishedAt": "2026-10-07T21:34:51Z", "picture": "https://encrypted-tbn2.gstatic.com/..."}],
    "timeWindowHours": 24
}
```

**Per-term format** (`outputFormat: "perTerm"`) - one row per term and geo (lists shortened; `relatedTopics*` are `null` unless `includeRelatedTopics` is enabled):

```json
{
    "type": "term", "searchTerm": "tea", "comparedWith": ["matcha"], "geo": "US", "timeRange": "today 12-m",
    "period": "2025-10-08 2026-10-08", "category": 0, "property": "web", "status": "ok",
    "averageInterest": 80.42, "peakInterest": 100, "peakDate": "2026-04-12", "latestInterest": 70, "resolution": "WEEK",
    "interestOverTime": [{"date": "2025-10-05", "timestamp": 1759622400, "value": 70, "isPartial": false}],
    "interestByRegion": [{"geoCode": "US-SD", "geoName": "South Dakota", "value": 95, "formattedValue": "95%", "hasData": true}],
    "regionValueType": "share", "regionResolution": "REGION",
    "relatedQueriesTop": [{"rank": 1, "query": "green tea", "value": 100, "formattedValue": "100", "isBreakout": false}],
    "relatedQueriesRising": [{"rank": 1, "query": "how to make cold brew tea", "value": 2050, "formattedValue": "+2,050%", "isBreakout": false}],
    "relatedTopicsTop": [{"rank": 1, "topicId": "/m/07clx", "topicTitle": "Tea", "topicType": "Beverage", "value": 100, "formattedValue": "100"}],
    "relatedTopicsRising": [{"rank": 1, "topicId": "/g/11y0w7h_p9", "topicTitle": "The Loaded Teashop", "topicType": "Topic", "value": 32100, "formattedValue": "Breakout", "isBreakout": true}],
    "error": null,
    "exploreUrl": "https://trends.google.com/trends/explore?q=tea%2Cmatcha&date=today%2012-m&geo=US"
}
```

Terms without enough search volume return a single `status` row (`no_data`, free). Terms that fail after all retries return `status: error` (free). A run summary with success rate and proxy statistics is saved to the key-value store as `SUMMARY`.

### Reliability - how it works and how we test it

Google Trends rate-limits aggressively (HTTP 429), redirects suspicious traffic to a captcha page and requires a session cookie plus per-widget tokens. This Actor:

1. **Warms every session** with a tiny request that sets Google's `NID` cookie, then calls the explore endpoint for widget tokens and the widget data endpoints (timeline, regions, related searches).
2. **Backs off on blocks** - on 429, 403, a captcha redirect or HTML instead of JSON, the Actor keeps the same session and proxy, honours Retry-After and backs off; after repeated blocks it stops requesting Google for the rest of the run and keeps what it has.
3. **One proxy for the whole run** - Apify datacenter proxy by default (or residential, if you pick that group). It never switches proxies when Google blocks it.
4. **Isolates errors per term and per section** - one failed term or section never breaks the rest; failed queries get a second pass with fresh sessions at the end of the run.

**Measured on the Apify platform (October 2026), with the earlier proxy settings (datacenter first, residential fallback; removed Nov 12, 2026), concurrency 5-10:** 5 stress runs, 413 terms across 15+ countries, worldwide, US states and metros, 10 time ranges (past 4 hours to 2004-present, custom dates), all 5 search properties and comparisons of up to 5 terms: **391 terms returned data, 22 genuinely low-volume terms returned no data, 0 failed** (100% completion), plus 225 Trending Now rows from 6 countries. Typical speed at the default concurrency of 5: 116 terms in 104 seconds; 55 terms + 150 trending searches in 76 seconds.

### Pricing

This Actor uses **pay-per-event** pricing – you pay per search term analysed and per trending search returned.

| Event | Price |
|---|---|
| Search term analysed (`term-result`) | **$3.00 per 1,000 terms** ($0.003 per term) |
| Trending search (`trending-search`) | $0.0005 per row |

Terms with no data and failed terms are **free**. Platform usage (compute) is included. Set **Maximum cost per run** in the run options to cap your spend – the Actor stops cleanly at the limit and keeps everything scraped so far.

### Related tools

Trends shows relative interest; Keyword Search Volume gives absolute monthly searches for the same terms.

- [Keyword Search Volume (Google Keyword Planner)](https://apify.com/wrenfield-data/keyword-search-volume): search volume, CPC and keyword ideas in bulk
- [AI Search Visibility Tracker](https://apify.com/wrenfield-data/ai-search-visibility-tracker): check if ChatGPT, Perplexity, Gemini and AI Overviews mention your brand
- [YouTube Transcript Scraper](https://apify.com/wrenfield-data/youtube-transcript-scraper): transcripts and subtitles from videos, channels and searches
- [Keyword Research Tool](https://apify.com/wrenfield-data/keyword-research-tool): keyword ideas with volume, KD, intent and SERP features
- [Google Autocomplete Keyword Expander](https://apify.com/wrenfield-data/google-autocomplete-keyword-expander): long-tail and question keywords from Google suggestions
- [People Also Ask Scraper](https://apify.com/wrenfield-data/people-also-ask-scraper): Google PAA questions, related searches and AI Overviews

All of these are maintained by the same developer and export flat JSON, CSV or Excel, so you can feed one tool's dataset into the next.

### Google Trends API: REST, Python, JavaScript, n8n and MCP

Actor ID for every client: **`wrenfield-data/google-trends-scraper`** (in URLs: `wrenfield-data~google-trends-scraper`). You need an [Apify API token](https://console.apify.com/settings/integrations); send it in an `Authorization: Bearer` header. Every example below sets `maxTotalChargeUsd`, a hard spend cap for the run.

**One request, rows back (runs up to 5 minutes):**

```bash
curl -X POST "https://api.apify.com/v2/acts/wrenfield-data~google-trends-scraper/run-sync-get-dataset-items?maxTotalChargeUsd=5" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["crm software", "email marketing"], "geos": ["US"], "timeRange": "today 12-m", "outputFormat": "perTerm"}'
```

**Python** (`pip install apify-client`):

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("wrenfield-data/google-trends-scraper").call(
    run_input={'searchTerms': ['crm software', 'email marketing'], 'geos': ['US'], 'timeRange': 'today 12-m', 'outputFormat': 'perTerm'},
    max_total_charge_usd=5,
)
for row in client.dataset(run.default_dataset_id).iterate_items():  # apify-client 1.x/2.x: run["defaultDatasetId"]
    print(row.get("searchTerm"), row.get("geo"), row.get("averageInterest"))
```

**JavaScript / TypeScript** (`npm i apify-client`):

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('wrenfield-data/google-trends-scraper').call(
    {"searchTerms": ["crm software", "email marketing"], "geos": ["US"], "timeRange": "today 12-m", "outputFormat": "perTerm"},
    { maxTotalChargeUsd: 5 },
);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

**Long or scheduled jobs (async + webhook):** start with `POST https://api.apify.com/v2/acts/wrenfield-data~google-trends-scraper/runs?maxTotalChargeUsd=5` (returns at once with `data.id` and `data.defaultDatasetId`), wait with `GET /v2/actor-runs/{id}?waitForFinish=60`, then read `GET /v2/datasets/{defaultDatasetId}/items?clean=true&format=json` (or `csv`, `xlsx`). To be called back instead of polling, add `&webhooks=` with the base64 of `[{"eventTypes":["ACTOR.RUN.SUCCEEDED"],"requestUrl":"https://your-app.example/hook"}]`. For recurring pulls, save the input as a task and put it on an Apify schedule.

**n8n:** Apify node → Resource *Actors* → *Run an Actor and Get Dataset* → Actor `wrenfield-data/google-trends-scraper` → custom input `{"searchTerms": ["crm software"], "geos": ["US"], "timeRange": "today 12-m", "outputFormat": "perTerm"}`. Make and Zapier have the same "run Actor" + "get dataset items" steps. Or call the `run-sync-get-dataset-items` URL above from any HTTP node.

**MCP (Claude, Cursor, VS Code, any MCP client):** `https://mcp.apify.com?tools=wrenfield-data/google-trends-scraper`. The tool exposes the input schema and output fields to the agent.

#### Output fields

Main fields (the Output tab and the dataset schema list every field with its type):

| Field | Type | Meaning |
| --- | --- | --- |
| `type` | string | Row type: interest_over_time, interest_by_region, related_query, related_topic, trending_now, term (per-term format) or status (no data / error, free) |
| `searchTerm` | string or null | Search term (or trending search) |
| `geo` | string or null | Geo code (WORLDWIDE for worldwide) |
| `timeRange` | string or null | Requested time range |
| `date` | string or null | Timeline point (YYYY-MM-DD, or ISO datetime for hourly data, UTC) (flat format) |
| `value` | integer or null | Interest 0-100 (region rows of comparisons: share %); related rows: relative value or % growth (flat format) |
| `isPartial` | boolean or null | Last timeline point is still being collected (flat format) |
| `geoCode` | string or null | Region code (e.g. US-CA, DMA 807) (flat format) |
| `geoName` | string or null | Region name (flat format) |
| `rankType` | string or null | top or rising (flat format) |
| `query` | string or null | Related query (flat format) |
| `isBreakout` | boolean or null | Rising more than 5000% (flat format) |
| `averageInterest` | number or null | Per-term format: mean interest |
| `peakInterest` | integer or null | Per-term: max interest |
| `latestInterest` | integer or null | Per-term: last value |
| `interestOverTime` | array or null | Per-term: timeline |
| `status` | string or null | ok, partial, no_data or error |
| `exploreUrl` | string or null | Open the same query on trends.google.com |
| `scrapedAt` | string or null | UTC timestamp |

Field names and types stay stable within version 1.x: we add fields but don't rename or remove them. Anything that changes a field will be announced in this README first. Optional fields can be `null` or absent depending on the options you set, so read them with a default.

#### Cost per 1,000 results

| Volume | Cost (free plan prices) | How it adds up |
| --- | --- | --- |
| 1,000 search terms (any number of rows each) | **$3.00** | $0.003 per term × geo; timeline, regions and related queries included |
| 1,000 Trending Now rows | **$0.50** | $0.0005 per trending search |

Terms with no data and failed terms are free. Platform usage is included. Paid Apify plans pay less (down to $1.95 per 1,000 terms).

#### Pipeline tips

- `"outputFormat": "flat"` (default) gives one row per timeline point, region or related query with a `type` column: best for SQL and spreadsheets. `"perTerm"` gives one row per term + geo with arrays inside: best for code.
- Up to 5 terms on one line (`"coffee, tea"`) share one 0-100 scale; separate lines are scraped independently.
- The last timeline point is often still being collected: check `isPartial` before alerting on a drop.

### FAQ

**Is there an official Google Trends API?**
Google offers a limited alpha API only to selected partners. This Actor gives you the same data the Google Trends website shows, as JSON/CSV, via the Apify API, schedules and integrations.

**Why does my Google Trends scraper / pytrends keep getting 429 errors?**
Google limits requests per IP and per session and wants a valid cookie. This Actor warms a valid session, backs off when Google rate-limits it and stops early instead of switching IPs or proxies; queries it could not scrape can be filled from the licensed DataForSEO Google Trends API (*Use licensed Google Trends fallback*).

**Why are related topics off by default?**
Google returns an empty related-topics list to regular automated sessions. When you enable `includeRelatedTopics`, the Actor requests related topics through Google Trends' embeddable-widget endpoint and sends a Referer header from a pool of public websites. Turn it on only if that method is acceptable for your use case. It adds 2 requests per term and doesn't change the price.

**What do the 0-100 values mean?**
Google Trends values are relative: 100 is the peak popularity for the term (or the highest of the compared terms) in the chosen geo and period. Compare terms in one line (up to 5) to put them on the same scale. Values for different queries or runs are not directly comparable, and Google samples data, so low-volume values can vary slightly between requests.

**How many keywords can I scrape?**
As many as you like - add hundreds of lines; they are processed in parallel and each is billed once per geo.

**Can I get daily trending searches?**
Yes - add country codes to *Trending now* (Google replaced the old Daily Search Trends page with Trending Now). Choose the past 4 hours, 24 hours, 48 hours or 7 days, filter by category and get news articles for each trend.

**Can I use it from Python, Make, Zapier, n8n or an AI agent?**
Yes - call the Actor through the Apify API, the Python/JavaScript client, the Apify MCP server or any Apify integration, and read the dataset items. Use `outputFormat: "perTerm"` for compact JSON.

**Is scraping Google Trends legal?**
The Actor collects publicly available, aggregated and anonymized statistics. No personal data is collected. Check the terms that apply to your use case.

### Feedback and support

Missing a field, hit an error, or need another country or option? Open an issue on the **Issues** tab and include the run ID. We read every issue and reply there.

### Acceptable use

- This Actor is an independent tool. It is not affiliated with, endorsed by or sponsored by Google. Google and Google Trends are trademarks of Google LLC.
- Use the data in line with the terms of the sources and the laws that apply to you.

# Actor input Schema

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

One search term (or Google Trends topic ID like <code>/m/02vqfm</code>) per line. To <b>compare</b> up to 5 terms on the same 0-100 scale, put them on one line separated by commas, e.g. <code>coffee, tea, matcha</code>. Add as many lines as you like - each line is scraped separately for every geo.

## `geos` (type: `array`):

Country code (<code>US</code>, <code>GB</code>, <code>DE</code>), region (<code>US-CA</code>, <code>GB-SCT</code>) or US metro (<code>US-NY-501</code>). Leave a line empty or write <code>WORLDWIDE</code> for worldwide. Every search term is scraped for every geo.

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

Preset period. Use <i>Custom time range</i> below for exact dates.

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

Optional, overrides the preset. <code>YYYY-MM-DD YYYY-MM-DD</code> (e.g. <code>2024-01-01 2024-12-31</code>) or hourly <code>YYYY-MM-DDTHH YYYY-MM-DDTHH</code> within the last 7 days (UTC).

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

Google Trends category ID to narrow ambiguous terms (0 = all categories). A number or a string id (e.g. <code>"71"</code>, as in apify/google-trends-scraper) both work. Common: 3 Arts & Entertainment, 5 Computers & Electronics, 7 Finance, 18 Shopping, 20 Sports, 44 Beauty & Fitness, 45 Health, 47 Autos & Vehicles, 66 Pets & Animals, 67 Travel, 71 Food & Drink, 958 Jobs & Education (full list in the README).

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

Which Google search product the interest comes from.

## `includeInterestOverTime` (type: `boolean`):

Timeline of search interest (0-100).

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

Interest per country / subregion / metro / city. When comparing several terms, values are each term's share (%) of the compared searches in that region, as on the Google Trends website.

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

Granularity of interest by region. Falls back to Google's default if the resolution isn't available for the geo.

## `includeLowSearchVolumeRegions` (type: `boolean`):

Also return regions with too little data (value 0).

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

Keep only the top N regions by interest.

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

Top and rising related searches (rising includes Breakout terms).

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

Off by default. Top and rising related topics. Google returns empty related topics to regular automated sessions, so when enabled this option requests them through Google Trends' embeddable-widget endpoint, sending a Referer header from a pool of public websites. Enable it only if this method is acceptable for your use case. Adds 2 requests per term; if topics can't be retrieved, the term is still returned with its other data.

## `maxRelatedItems` (type: `integer`):

Maximum rows per top / rising list.

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

Get the current Trending Now / daily trending searches for these countries (e.g. <code>US</code>, <code>GB</code>, <code>IN</code>, or a region like <code>US-CA</code>). Works with or without search terms.

## `trendingHours` (type: `string`):

Trends that started within this window.

## `trendingCategories` (type: `array`):

Optional filter. Empty = all categories.

## `trendingActiveOnly` (type: `boolean`):

Skip trends that have already ended.

## `maxTrendingPerGeo` (type: `integer`):

Google lists up to ~500 trends per day for big countries; ranked by relevance.

## `includeTrendingNews` (type: `boolean`):

Attach up to 3 news articles (title, URL, source, time, image) that Google links to each trending search. One extra request per 50 trends.

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

Flat: every timeline point, region, related query and topic is its own row with a <code>type</code> column. Per term: one row per search term + geo with arrays inside. Price is the same - you pay per term, not per row.

## `advancedQueries` (type: `array`):

Optional. Fine-grained list of queries, each with its own geo / time range / category / property, e.g. <code>\[{"terms": "nike, adidas", "geo": "DE", "timeRange": "today 5-y", "category": 0, "property": "youtube"}]</code>. Missing fields use the values above.

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

Language of region and topic names, e.g. <code>en-US</code>, <code>de</code>, <code>fr</code>.

## `timezoneOffsetMinutes` (type: `integer`):

Google's tz parameter (minutes behind UTC, e.g. 300 = US Eastern standard time). Default 0 = UTC dates.

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

Defaults to Apify datacenter proxy. Choose the RESIDENTIAL group to use residential IPs for the whole run. The Actor stays on the proxy you choose: if Google rate-limits it, it backs off (Retry-After honoured) and, after repeated blocks, stops early; queries it could not scrape use the licensed fallback below when it is on. It never switches proxies or IPs to get around a block.

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

Queries processed in parallel.

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

Each attempt uses a fresh session (new IP + new cookie) with exponential backoff.

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

Country code as a single string (e.g. <code>US</code>). Empty = worldwide. Used when Geo list is empty. Same as <code>geo</code> in apify/google-trends-scraper.

## `isMultiple` (type: `boolean`):

Same as <code>isMultiple</code> in apify/google-trends-scraper. On (default): commas in a searchTerms line compare up to 5 terms (Google's limit). Off: each line is one search term, commas included.

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

Maximum number of term×geo queries to run. 0 = no limit.

## `startUrls` (type: `array`):

Paste Google Trends explore URLs; each is turned into a query (q, geo, date, cat). Also accepts apify/google-trends-scraper's format: <code>\[{"url": "…"}]</code> or <code>\[{"requestsFromUrl": "…"}]</code>.

## `viewedFrom` (type: `string`):

Same as <code>viewedFrom</code> in apify/google-trends-scraper: 2-letter country for the proxy (e.g. <code>us</code>). Optional.

## `spreadsheetId` (type: `string`):

Same as <code>spreadsheetId</code> in apify/google-trends-scraper: a public Google Sheet (Anyone with the link). Terms are read from the first column; row 1 is the header. Added to Search terms.

## `maxRequestRetries` (type: `integer`):

Same as <code>maxRequestRetries</code> in apify/google-trends-scraper. Used as Max retries when that is not set.

## `pageLoadTimeoutSecs` (type: `integer`):

Accepted so apify/google-trends-scraper inputs work unchanged. Not needed here: we don't load full browser pages per term.

## `skipDebugScreen` (type: `boolean`):

Accepted so apify/google-trends-scraper inputs work unchanged. We never save page snapshots.

## `dataforseoFallback` (type: `boolean`):

If the browser scrape fails after retries, fetch interest-over-time from DataForSEO's Google Trends API (~$0.011 per call on the Actor owner's account; you are not charged extra beyond the normal term-result event). Related queries/regions are not included in the fallback.

## Actor input object example

```json
{
  "searchTerms": [
    "coffee",
    "tea, matcha"
  ],
  "geos": [
    "US"
  ],
  "timeRange": "",
  "category": 0,
  "property": "web",
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "regionResolution": "auto",
  "includeLowSearchVolumeRegions": false,
  "maxRegions": 250,
  "includeRelatedQueries": true,
  "includeRelatedTopics": false,
  "maxRelatedItems": 25,
  "trendingGeos": [
    "US"
  ],
  "trendingHours": "24",
  "trendingActiveOnly": false,
  "maxTrendingPerGeo": 10,
  "includeTrendingNews": true,
  "outputFormat": "flat",
  "language": "en-US",
  "timezoneOffsetMinutes": 0,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxConcurrency": 5,
  "maxRetries": 8,
  "isMultiple": true,
  "maxItems": 0,
  "dataforseoFallback": true
}
```

# Actor output Schema

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

No description

## `perTerm` (type: `string`):

No description

## `summary` (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 = {
    "searchTerms": [
        "coffee",
        "tea, matcha"
    ],
    "geos": [
        "US"
    ],
    "trendingGeos": [
        "US"
    ],
    "maxTrendingPerGeo": 10,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("wrenfield-data/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": [
        "coffee",
        "tea, matcha",
    ],
    "geos": ["US"],
    "trendingGeos": ["US"],
    "maxTrendingPerGeo": 10,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("wrenfield-data/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": [
    "coffee",
    "tea, matcha"
  ],
  "geos": [
    "US"
  ],
  "trendingGeos": [
    "US"
  ],
  "maxTrendingPerGeo": 10,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call wrenfield-data/google-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,wrenfield-data/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/gfWlw2NKtfojXodOt/builds/8bHnNwPz6lT9ZIEEl/openapi.json