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

Interest over time, interest by region, related queries and related topics for any keyword, plus daily Trending Now searches. Bounded retries on fresh sessions; failed terms are never charged.

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

## Pricing

from $2.00 / 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.

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

Get Google Trends data for any keyword: **interest over time, interest by region and related queries** (top and rising). It also returns **Trending Now**, the daily trending searches for any country. Results come back as clean JSON, ready for a spreadsheet, a dashboard or an AI agent.

**You only pay for terms that succeed.** When Google blocks a request, the scraper retries on a fresh proxy session, with a cap on the number of retries. A term that still can't be fetched is listed in the `FAILED_TERMS` record and never charged. Runs don't hang until a timeout and don't bill you for empty rows.

### What you can use it for

- **SEO and content planning:** find rising queries before your competitors do, and check whether a topic is growing or fading.
- **Market and product research:** compare up to 5 brands, products or ideas on one chart, the way Google Trends' compare view does.
- **Regional targeting:** see which states, metro areas or countries search for something most.
- **E-commerce and seasonality:** use 5-year history and Google Shopping search interest to time inventory and campaigns.
- **News and social monitoring:** pull today's Trending Now searches, with their news articles, on a schedule.
- **AI agents and automations:** a small, predictable JSON output with one result per keyword.

### How to use it

1. Enter one or more **search terms**.
2. Optionally pick a **location** (e.g. `US`, `GB`, `US-CA`), a **time range** and a **search type** (web, images, news, Shopping, YouTube).
3. Turn on **Compare terms** to put up to 5 terms on one chart. Values are then relative to each other.
4. Click **Start**. Each term, or each comparison group, produces one result.

For daily trending searches, set **Mode** to *Trending Now* and choose a country.

#### Example input

```json
{
  "searchTerms": ["chatgpt", "claude", "gemini"],
  "compareTerms": true,
  "geo": "US",
  "timeRange": "today 3-m"
}
```

### Output

One result per term (or per comparison group):

```json
{
  "searchTerm": null,
  "searchTerms": ["chatgpt", "claude", "gemini"],
  "geo": "US",
  "timeRange": "today 3-m",
  "category": 0,
  "searchProperty": "web",
  "averages": { "chatgpt": 67, "claude": 18, "gemini": 28 },
  "interestOverTime": [
    { "date": "2026-10-26T00:00:00+00:00", "formattedTime": "Oct 26, 2026",
      "values": { "chatgpt": 78, "claude": 24, "gemini": 36 }, "isPartial": true }
  ],
  "interestByRegion": [
    { "geoCode": "US-CA", "geoName": "California", "values": { "chatgpt": 57, "claude": 18, "gemini": 25 } }
  ],
  "relatedQueries": {
    "chatgpt": {
      "top":    [{ "query": "chatgpt ai", "value": 100, "formattedValue": "100" }],
      "rising": [{ "query": "chatgpt student offer", "value": 500, "formattedValue": "+500%" }]
    }
  },
  "hasData": true,
  "scrapedAt": "2026-10-26T13:58:06+00:00"
}
```

For a single term, `relatedQueries` is `{ "top": [...], "rising": [...] }` directly.

Trending Now results contain `rank`, `title`, `approxTraffic`, `pubDate`, `picture` and the related `news` articles.

All values are Google's 0–100 relative interest index, exactly as Google Trends shows them.

### Pricing

You pay per result: one result per term, comparison group or trending search. Runs where every term fails cost nothing. See the Pricing tab for current rates.

### Tips

- **Proxy:** Apify datacenter proxies (the default) work for Google Trends. If you see repeated 429 responses on large runs, switch the proxy group to RESIDENTIAL.
- **Large lists:** keep *Parallel requests* at 2–3. Raising it makes runs faster but triggers more rate limits and retries.
- **Hourly ranges** (`now 1-H` to `now 7-d`) use the *Timezone offset* setting.
- **Related topics:** as of October 2026 Google returns an empty related-topics list to automated requests, so the option is off by default. Related queries work normally.

### FAQ

**Why do numbers differ slightly between runs?** Google Trends samples its data, so small differences between runs are normal and also appear in the Google Trends website.

**Is this data public?** Yes. This Actor reads the same aggregated, anonymous search-interest data the Google Trends website shows. It collects no personal data.

**Something broke?** Open an issue on the Issues tab with your run ID. Fixes are usually live the same day.

# Actor input Schema

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

Explore: interest over time, by region, related queries and topics for your search terms. Trending Now: today's trending searches for a country.

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

Keywords to look up. Each term becomes one result unless you turn on comparison.

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

Put up to 5 terms on one chart, the way Google Trends' compare view does. Values are then relative across the terms, and you get one result for the group.

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

Country or region code, such as US, GB, DE or US-GA. Leave empty for worldwide. In Trending Now mode, empty means US.

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

Google Trends time window, in Google's own notation (for example "today 12-m" is the past 12 months, "now 7-d" the past 7 days).

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

Overrides the preset. Format: YYYY-MM-DD YYYY-MM-DD, for example 2025-01-01 2025-06-30.

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

Google Trends category number. 0 means all categories.

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

Which Google property to measure interest on: web search (empty), Images, News, Shopping (froogle) or YouTube.

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

Include the interest-over-time series (0 to 100) for each term.

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

Include the interest-by-region breakdown for each term.

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

Include related queries, both top and rising, for each term.

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

As of October 2026 Google returns an empty topics list to automated requests, so this is off by default.

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

Granularity of interest by region. Google's default depends on the location you chose.

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

Also list regions with very low search volume in the interest-by-region data.

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

Stop after this many results. 0 means no limit.

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

Interface language for topic names, such as en-US or de.

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

Minutes offset from UTC that Google uses for hourly ranges. 0 = UTC, 300 = US Eastern standard time.

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

Terms fetched at the same time. Higher is faster but more likely to be rate-limited.

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

Each retry uses a fresh proxy session. Terms that still fail are listed in FAILED_TERMS and are not charged.

## `requestTimeoutSecs` (type: `integer`):

How long to wait for a single HTTP response before the attempt counts as failed and is retried on a fresh session.

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

Proxy settings. Apify datacenter proxies (the default) work for Google Trends; switch to the RESIDENTIAL group only if you see repeated 429 responses.

## Actor input object example

```json
{
  "mode": "explore",
  "searchTerms": [
    "web scraping",
    "artificial intelligence"
  ],
  "compareTerms": false,
  "geo": "",
  "timeRange": "today 12-m",
  "category": 0,
  "searchProperty": "",
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "includeRelatedQueries": true,
  "includeRelatedTopics": false,
  "regionResolution": "",
  "includeLowVolumeRegions": false,
  "maxItems": 0,
  "language": "en-US",
  "timezoneOffset": 0,
  "maxConcurrency": 2,
  "maxRetries": 6,
  "requestTimeoutSecs": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

Dataset results in the "Overview" view.

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

Dataset results in the "Trending Now" view.

## `failed` (type: `string`):

JSON list of search terms that failed after every retry, with the error for each. Empty when everything succeeded. Failed inputs are never charged.

# 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": [
        "web scraping",
        "artificial intelligence"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("signalclear/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": [
        "web scraping",
        "artificial intelligence",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

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

```

## MCP server setup

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