# Google Trends Scraper (`axiomworks/google-trends-scraper`) Actor

Scrape Google Trends for keywords or topic IDs: interest over time, interest by region, related queries and related topics as flat rows, or current Trending Now searches per country. Compare up to five terms on one 0-100 scale. Filter by country, time range, category and property.

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

## Pricing

from $1.75 / 1,000 results

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

**Returns:** one row per term and time bucket, region, related result or trend with type, searchTerms, geo, date, value, query, sourceUrl.
**Input:** `{"searchTerms":["bitcoin"],"geo":"US","timeRange":"today 3-m","outputs":["interestOverTime","relatedQueries"],"maxItems":100}`
**Best for:** keyword research, regional comparisons, monitoring search interest using Google Trends scraper API output.

```json
{"type": "trending_now", "title": "interpol", "geo": "FR", "approxTraffic": "200+", "approxTrafficNumber": 200, "pubDate": "2026-10-12T23:00:00.000Z", "sourceUrl": "https://trends.google.com/trending/rss?geo=FR"}
```

### What does Google Trends Scraper do?

Google Trends Scraper saves public explore data and Trending Now searches as flat dataset rows:

- **Interest over time**: Google's 0-100 popularity index for each term, per hour, day, week or month depending on the time range you pick.
- **Interest by region**: the same index broken down by country, state, metro area (DMA) or city.
- **Related queries**: the top and rising searches related to each term, with Google's value and label (for example `+1,700%` or `Breakout`).
- **Related topics**: the top and rising related Knowledge Graph topics, when Google returns them.
- **Trending Now**: the current trending searches for one or more countries, with approximate search volume, publish time, a picture and related news articles.
- **News for your terms**: when a current Trending Now story matches the term, explore rows also carry its news articles and picture; otherwise these fields are null.

You can give it plain keywords (`bitcoin`), Google topic IDs (`/m/05p0rrx`), or Google Trends explore URLs that you copied from your browser. Up to 5 terms can be compared in one request so their values share the same scale.

The `type` column identifies the row kind for spreadsheet or database workflows.

### What data can you get from Google Trends?

Each dataset row contains these fields.

| Field | What it contains |
|---|---|
| `type` | `interest_over_time`, `interest_by_region`, `related_query`, `related_topic` or `trending_now` |
| `searchTerms` | The terms in the request (the comparison group), or the trending search |
| `geo` | The geo code of the request, `''` for worldwide |
| `timeRange` | The time range of the explore request, e.g. `today 12-m` |
| `date` | ISO start of the data point or window, or the publish time of a trending search |
| `formattedTime` | Google's label for the period, e.g. `Sep 6 – 12, 2026` or `Past 12 months` |
| `values` | Map of term to value, e.g. `{"bitcoin": 19, "ethereum": 2}` |
| `isPartial` | `true` when the period includes today and the value can still change |
| `rank`, `isBreakout` | Position in Google's top or rising list and whether a rising row is a 'Breakout' (related queries and topics rows only; null elsewhere) |
| `geoCode`, `geoName` | The region of the row (e.g. `US-CA`, `California`) or of the request |
| `keyword` | The search term the row belongs to |
| `listType` | `top` or `rising` for related rows; `timeline`, `region` or `trending` otherwise |
| `query` | Related query text, topic title, search term or trending search |
| `topicTitle`, `topicType`, `topicMid` | Google Knowledge Graph topic for the row (related topic, or the best match for the keyword) |
| `value`, `formattedValue` | The row's number and Google's label for it |
| `exploreLink` | Google Trends explore URL for the row's term or related item |
| `title` | Row label: search term, related query or topic, or trending search |
| `approxTraffic`, `approxTrafficNumber` | Approximate search volume such as `1000+` (trending_now rows only; null on explore rows, use `value` there) |
| `pubDate` | Publish time of the trending search (trending_now rows only; null on explore rows, use `date`) |
| `picture` | Image URL of the trending search, or of the first news article on explore rows |
| `newsItems` | News articles from Google Trends Trending Now: title, url, source, picture |
| `newsTrend` | The Trending Now story the picture and news come from |
| `newsMatch` | `term` when a Trending Now story matches the search term, `none` when no story matched (then `picture`, `newsItems` and `newsTrend` are null) |
| `sourceUrl` | The Google Trends endpoint the row was read from |
| `id` | Stable row ID, unique within the run |
| `scrapedAt` | When the row was saved |

A note on the numbers: Google Trends values are relative, not absolute. For each request, Google scales the results so the highest point is 100. Values from two separate requests are therefore not on the same scale. If you want to compare terms with each other, turn on `compareTerms` so they are sent together (up to 5 per request).

### How to use Google Trends Scraper

1. Open the Actor in Apify Console and go to the **Input** tab.
2. Choose a **mode**. `explore` gives time series, regions and related searches for your terms. `trendingNow` gives today's trending searches.
3. For `explore`, type your **search terms** (one per line) or paste Google Trends explore URLs into **Start URLs**.
4. Pick a **geo** (for example `US`, `GB` or `US-CA`, or leave it empty for worldwide) and a **time range**.
5. Choose which **outputs** you need. Fewer outputs means fewer rows and a faster run.
6. Set **maxItems** to cap the number of rows.
7. Click **Start**. When the run finishes, open the **Output** tab to view the rows, or export them as JSON, CSV, Excel or HTML.

For `trendingNow`, set **Trending Now countries** to the country codes you want, such as `US`, `GB`, `DE` and `IN`. Each country usually has 10 to 20 current trending searches.

### Input

| Field | Type | Description |
|---|---|---|
| `searchTerms` | array | Keywords or topic IDs, e.g. `["bitcoin", "ethereum"]`. Required in explore mode unless `startUrls` is set |
| `mode` | string | `explore` (default) or `trendingNow` |
| `compareTerms` | boolean | Send up to 5 terms per request so their values are comparable. Default `false` |
| `startUrls` | array | Google Trends explore URLs. The Actor reads their `q`, `geo` and `date` parameters |
| `geo` | string | Country or subregion code, e.g. `US` or `US-CA`. Empty means worldwide |
| `geos` | array | Optional list of geo codes, e.g. `["US", "GB", "DE"]`, to run every term in each location in one run. Overrides `geo` when set |
| `timeRange` | string | `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 `YYYY-MM-DD YYYY-MM-DD` |
| `outputs` | array | Any of `interestOverTime`, `interestByRegion`, `relatedQueries`, `relatedTopics`. Default: all four |
| `category` | integer | Google Trends category ID. `0` (default) means all categories |
| `property` | string | `web` (default), `images`, `news`, `froogle` (Shopping) or `youtube` |
| `regionResolution` | string | `COUNTRY`, `REGION`, `DMA` or `CITY`. Empty lets Google choose |
| `trendingGeos` | array | Country codes for `trendingNow`. Default `["US"]` |
| `trendingMinTraffic` | integer | Minimum RSS `approxTrafficNumber`; 0 disables filtering |
| `trendingMaxAgeHours` | number | Maximum RSS publication age in hours; 0 disables filtering |
| `resolveTrendingTopics` | boolean | true by default; false skips Trending Now topic lookups |
| `maxItems` | integer | Maximum number of rows for the whole run. Default 1000 |
| `language` | string | Language code for labels, e.g. `en-US` (default) |
| `timezoneOffset` | integer | Timezone offset in minutes. Default `0` (UTC) |
| `proxyConfiguration` | object | Proxy settings. Apify residential proxy is the default |

Example input for explore mode:

```json
{
    "mode": "explore",
    "searchTerms": ["bitcoin", "ethereum"],
    "compareTerms": true,
    "geo": "US",
    "timeRange": "today 12-m",
    "outputs": ["interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics"],
    "maxItems": 500
}
```

Example input with an explore URL:

```json
{
    "mode": "explore",
    "startUrls": [{ "url": "https://trends.google.com/trends/explore?q=iphone&geo=GB&date=now%207-d" }],
    "outputs": ["interestOverTime", "relatedQueries"]
}
```

Example input for Trending Now:

```json
{
    "mode": "trendingNow",
    "trendingGeos": ["US", "GB", "DE", "IN"]
}
```

Invalid input names the field to correct. Valid targets with no data succeed with zero rows and a status suggesting broader terms, geography or timeRange. Blocked targets retry with fresh sessions; slow targets stop after a bounded attempt. Other targets continue.

For a recent-news shortlist, set `trendingMaxAgeHours` to 24 and `trendingMinTraffic` to a lower-bound search count. Both default to 0, which disables filtering. Age means RSS publication age, not when interest first started. Enabled filters exclude rows missing the relevant value and run before the shared `maxItems` cap. A restrictive filter can legitimately return no rows.

Set `resolveTrendingTopics` to false for an RSS-only run. This skips each title's autocomplete lookup while retaining traffic, publication dates, pictures and news. Topic fields can be absent. Its default remains true for compatibility. This option changes only Trending Now; explore topic lookups keep their existing behavior. Each country still supplies Google's RSS shortlist, not the full Trending Now list.

### Output

These rows come from a local test run (`sourceUrl` shortened). An interest-over-time row (no Trending Now story matched this term, so the news fields are null):

```json
{
    "type": "interest_over_time",
    "searchTerms": [
        "bitcoin"
    ],
    "geo": "US",
    "timeRange": "today 3-m",
    "date": "2026-06-30T00:00:00.000Z",
    "formattedTime": "Jun 30, 2026",
    "values": {
        "bitcoin": 100
    },
    "isPartial": false,
    "geoCode": "US",
    "geoName": "United States",
    "keyword": "bitcoin",
    "listType": "timeline",
    "query": "bitcoin",
    "topicTitle": "Bitcoin",
    "topicType": "Cryptocurrency",
    "topicMid": "/m/05p0rrx",
    "value": 100,
    "formattedValue": "100",
    "approxTraffic": null,
    "approxTrafficNumber": null,
    "exploreLink": "https://trends.google.com/trends/explore?q=bitcoin&date=today+3-m&geo=US",
    "title": "bitcoin",
    "pubDate": null,
    "picture": null,
    "newsItems": null,
    "newsTrend": null,
    "newsMatch": "none",
    "sourceUrl": "https://trends.google.com/trends/api/widgetdata/multiline?...",
    "id": "15367e74168d5a1bc483",
    "scrapedAt": "2026-09-30T05:42:28.653Z"
}
```

A rising related query (news columns left out for brevity):

```json
{
    "type": "related_query",
    "searchTerms": ["iphone"],
    "geo": "GB",
    "timeRange": "now 7-d",
    "date": "2026-09-23T05:28:41.000Z",
    "formattedTime": "Past 7 days",
    "pubDate": null,
    "isPartial": true,
    "geoCode": "GB",
    "geoName": "United Kingdom",
    "keyword": "iphone",
    "listType": "rising",
    "value": 450,
    "formattedValue": "+450%",
    "approxTraffic": null,
    "approxTrafficNumber": null,
    "exploreLink": "https://trends.google.com/trends/explore?q=iphone+16+review&date=now+7-d&geo=GB",
    "query": "iphone 16 review",
    "title": "iphone 16 review",
    "values": { "iphone 16 review": 450 },
    "topicTitle": "iPhone",
    "topicType": "Mobile phone",
    "topicMid": "/m/027lnzs",
    "sourceUrl": "https://trends.google.com/trends/api/widgetdata/relatedsearches?...",
    "id": "82e88f5126c17d787f55",
    "scrapedAt": "2026-09-30T05:28:49.368Z"
}
```

A Trending Now row from a local RSS-only run in France (news shortened to one article):

```json
{
  "type": "trending_now",
  "searchTerms": [
    "interpol"
  ],
  "geo": "FR",
  "title": "interpol",
  "approxTraffic": "200+",
  "approxTrafficNumber": 200,
  "pubDate": "2026-10-12T23:00:00.000Z",
  "sourceUrl": "https://trends.google.com/trending/rss?geo=FR",
  "id": "6eee9d1f48e8fc52d802",
  "scrapedAt": "2026-10-13T00:24:20.173Z",
  "newsItems": [
    {
      "title": "TRON: Post-Quantum Cryptography Hits Testnet",
      "url": "https://blockchain.news/flashnews/tron-post-quantum-cryptography-hits-testnet",
      "source": "Blockchain News",
      "picture": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcSuuKwuXZ9t5V5UuEidNyxqezmLxXcqdYbDKpO0e34yTDZ_3kb19yxgGZI34f4"
    }
  ]
}
```

### How much does it cost to scrape Google Trends?

The Actor uses pay-per-event pricing. You pay one result event per dataset row. See the **Pricing** tab of the Actor page for the current rate.

To keep costs down, request only the `outputs` you need, because interest by region and related queries add many rows per term. The `maxItems` input puts a hard limit on how many rows one run can return, so you never pay for more rows than you asked for. You can also turn on `compareTerms` to send up to 5 terms in one request; each row then lists the whole group in `searchTerms` and its own term in `keyword`.

### Use with AI agents (MCP)

AI agents and assistants can run this Actor through the Apify MCP server. Add this server to your MCP client (Claude Desktop, Cursor, VS Code and other clients that support MCP):

```json
{
    "mcpServers": {
        "apify": {
            "url": "https://mcp.apify.com/?tools=axiomworks/google-trends-scraper"
        }
    }
}
```

The hosted server at `https://mcp.apify.com` authenticates with your Apify account using OAuth. The tool name is `axiomworks/google-trends-scraper`. The agent then sees the input schema of this Actor and can start runs and read the results.

Example prompts:

- "Use Google Trends Scraper to compare interest in bitcoin and ethereum in the US over the past 12 months, and tell me in which weeks ethereum was highest relative to bitcoin."
- "Get the rising related queries for 'electric car' in Germany for the past 3 months and group them by brand."
- "What is trending right now in the US, UK and India? List each trending search with its approximate traffic and one news headline."
- "Which US states search most for 'pickleball' this year?"

#### Use it from an AI agent

Connect to Apify’s hosted MCP server at `https://mcp.apify.com` with OAuth and select `axiomworks/google-trends-scraper`. Read both the dataset and the linked `RUN_SUMMARY` record. This uncharged JSON array records each explore group/location, URL or Trending Now country with `input`, `status`, `reason`, and `itemCount`. Status is `ok` for returned rows, `0-items` for empty or skipped targets, `blocked` after exhausted block retries, or `invalid` for failed validation. Comparison groups count all their terms. Reasons identify skipped targets and partial widget failures. Malformed input fails the run.

For API calls, set `APIFY_RUN_CAP` to your spending cap. Pass it as a run query parameter, outside Actor input:

```bash
curl -X POST "https://api.apify.com/v2/acts/axiomworks~google-trends-scraper/runs?maxTotalChargeUsd=${APIFY_RUN_CAP}" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["bitcoin"],"outputs":["interestOverTime"],"maxItems":7}'
```

### Integrations and API

You can start the Actor and read its results from your own code with the Apify API. Set your Apify API token in the `APIFY_TOKEN` environment variable.

Python (`pip install apify-client`):

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("axiomworks/google-trends-scraper").call(run_input={
    "searchTerms": ["bitcoin", "ethereum"],
    "compareTerms": True,
    "geo": "US",
    "timeRange": "today 12-m",
    "outputs": ["interestOverTime"],
})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["date"], row["keyword"], row["value"])
```

JavaScript (`npm install apify-client`):

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('axiomworks/google-trends-scraper').call({
    mode: 'trendingNow',
    trendingGeos: ['US', 'GB'],
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
for (const row of items) console.log(row.geo, row.title, row.approxTraffic);
```

cURL (runs the Actor and returns the rows in one call):

```bash
curl -X POST "https://api.apify.com/v2/acts/axiomworks~google-trends-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms": ["bitcoin"], "geo": "US", "timeRange": "today 3-m", "outputs": ["interestOverTime", "relatedQueries"], "maxItems": 100}'
```

The Actor also works with Apify Console integrations such as schedules, webhooks, Google Sheets, Slack, Make and Zapier.

### FAQ

**Why are the values between 0 and 100?**
Google Trends does not publish search counts for explore data. It publishes an index where 100 is the peak popularity within the request. The Actor returns exactly what Google returns.

**Can I compare more than 5 terms?**
Google accepts at most 5 terms per request. With `compareTerms` on, the Actor splits longer lists into groups of 5. Values are comparable within a group, but not across groups.

**What do traffic and news fields contain on explore rows?**
Traffic fields are null. News fields contain articles and a picture only for a matching Trending Now story; otherwise they are null and `newsMatch` is `none`.

**What if Google throttles a request?**
The Actor retries with backoff, then moves on to the next term.

### Is it legal to scrape Google Trends?

Google Trends data is public and aggregated. This independent Actor reads public endpoints without login.

Check Google's terms and local laws before republishing the data. This Actor is an independent tool and is not affiliated with, endorsed by or sponsored by Google.

### Feedback

Report bugs through the Actor’s **Issues** tab with input and run ID.

# Actor input Schema

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

Search keywords or topic IDs, e.g. \["bitcoin"] or \["/m/05p0rrx"]. No API default: explore requires these or startUrls; both add jobs. Ignored in trendingNow. compareTerms groups up to five; geos overrides geo. All targets share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed input fails validation.

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

Choose explore (default) for outputs using searchTerms or startUrls, or trendingNow for RSS using trendingGeos. trendingNow ignores explore terms, URLs and filters. All targets and outputs share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed input fails validation.

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

Compare searchTerms in explore mode: false (default) requests each separately; true groups up to five with a shared relative scale. Groups are independent, not normalized across groups. startUrls already define their own groups; ignored in trendingNow. All groups share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED.

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

Add explore jobs from URL objects, e.g. \[{"url":"https://trends.google.com/trends/explore?q=iphone\&geo=GB\&date=now%207-d"}]. Default \[] adds none. Requires explore; combines with searchTerms. q, geo and date override geo/timeRange for each URL; UI URLs are never fetched. All jobs share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed URLs fail validation.

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

Set an explore country/subregion, e.g. US or US-CA; default "" requests worldwide. Applies to searchTerms unless geos is nonempty; a startUrls geo parameter overrides it. Ignored in trendingNow, which uses trendingGeos. All locations share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed codes fail validation.

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

Request searchTerms in each explore location, e.g. \["US","GB","US-CA"]. Default \[] uses geo; nonempty overrides geo. Does not override startUrls geo parameters; ignored in trendingNow. All locations, terms and outputs share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed codes fail validation.

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

Choose an explore period: 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 YYYY-MM-DD YYYY-MM-DD. startUrls date overrides it; ignored in trendingNow. All periods and outputs share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed ranges fail validation.

## `outputs` (type: `array`):

Select explore datasets: interestOverTime, interestByRegion, relatedQueries, relatedTopics. Default (or \[]) requests all four; ignored in trendingNow. Requires searchTerms or startUrls. relatedTopics is best effort and may be empty. All selected outputs and targets share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED.

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

Filter explore by a nonnegative Google category ID, e.g. 7 for Finance. Default 0 includes all categories. Used with searchTerms and startUrls; ignored in trendingNow. All filtered targets and outputs share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed IDs fail validation.

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

Select web (default; "" also means web), images, news, froogle (Shopping), or youtube. Filters explore searchTerms and startUrls; ignored in trendingNow. All filtered targets and outputs share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; unknown choices fail validation.

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

Choose auto (default: Google chooses), COUNTRY, REGION, DMA (US metros), or CITY. Applies only when explore outputs includes interestByRegion; availability depends on geo/geos or startUrls. Ignored for other outputs and trendingNow. All regions share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; unknown choices fail validation.

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

Choose country codes for trendingNow, e.g. \["US","GB","DE"]. Default \["US"] requests the US RSS feed; ignored in explore. Uses these countries instead of geo/geos and ignores explore filters. RSS can return fewer rows than requested. All countries share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed codes fail validation.

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

Cap dataset rows across all terms, comparison groups, URLs, countries and outputs. Positive integer, default 1000. Applies to both modes; comparisons can produce multiple rows per time point. Stops saving at this shared limit; skipped targets appear in RUN_SUMMARY. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed limits fail validation.

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

Set Google label language, e.g. en-US (default) or de. Used in explore requests and topic lookups in both modes; does not change supplied terms or RSS news language. Works with timezoneOffset for explore labels. All targets share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed language codes fail validation.

## `timezoneOffset` (type: `integer`):

Set integer Google tz minutes from -1440 to 1440; default 0 uses UTC, e.g. 300 for UTC-5. Used with language for explore buckets and topic lookups; not an IANA timezone or RSS publication-time conversion. All targets share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; malformed offsets fail validation.

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

Configure Google requests in both modes. Default uses Apify RESIDENTIAL proxy. Temporary blocks retry with backoff on a fresh session; no CAPTCHA solving. Applies to all targets independently of filters; all targets share maxItems. Bad, blocked or empty targets yield 0 items and SUCCEEDED; RUN_SUMMARY reports persistent blocks.

## `trendingMinTraffic` (type: `integer`):

Keep Trending Now RSS rows whose approxTrafficNumber lower bound is at least this number. Default 0 disables filtering. Rows with missing traffic are excluded when enabled; explore mode ignores this field. Filters apply before the shared maxItems limit.

## `trendingMaxAgeHours` (type: `number`):

Keep Trending Now RSS rows published within this many hours of the run. Default 0 disables filtering. Uses pubDate, not the trend start time. Missing publication dates are excluded when enabled; explore mode ignores this field.

## `resolveTrendingTopics` (type: `boolean`):

Look up Knowledge Graph topicTitle, topicType and topicMid for each Trending Now title. Default true preserves topic lookup. Set false for RSS-only runs with fewer upstream requests; topic fields can then be absent. Explore topic lookup is unchanged.

## Actor input object example

```json
{
  "searchTerms": [
    "bitcoin"
  ],
  "mode": "explore",
  "compareTerms": false,
  "startUrls": [],
  "geo": "US",
  "geos": [],
  "timeRange": "today 3-m",
  "outputs": [
    "interestOverTime",
    "relatedQueries"
  ],
  "category": 0,
  "property": "web",
  "regionResolution": "auto",
  "trendingGeos": [
    "US"
  ],
  "maxItems": 100,
  "language": "en-US",
  "timezoneOffset": 0,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "trendingMinTraffic": 0,
  "trendingMaxAgeHours": 0,
  "resolveTrendingTopics": true
}
```

# Actor output Schema

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

No description

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

Uncharged JSON RUN_SUMMARY: one entry per explore comparison group and geography, explore URL, or Trending Now country, with input, status (ok, 0-items, blocked, invalid), reason and itemCount. Includes targets skipped at maxItems.

# 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": [
        "bitcoin"
    ],
    "mode": "explore",
    "geo": "US",
    "timeRange": "today 3-m",
    "outputs": [
        "interestOverTime",
        "relatedQueries"
    ],
    "trendingGeos": [
        "US"
    ],
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("axiomworks/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": ["bitcoin"],
    "mode": "explore",
    "geo": "US",
    "timeRange": "today 3-m",
    "outputs": [
        "interestOverTime",
        "relatedQueries",
    ],
    "trendingGeos": ["US"],
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("axiomworks/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": [
    "bitcoin"
  ],
  "mode": "explore",
  "geo": "US",
  "timeRange": "today 3-m",
  "outputs": [
    "interestOverTime",
    "relatedQueries"
  ],
  "trendingGeos": [
    "US"
  ],
  "maxItems": 100
}' |
apify call axiomworks/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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