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

Fast, reliable Google Trends API: interest over time, by region, related queries for 1–5,000 keywords per run. Compare up to 5 terms. No browser; auto-retry with fresh IPs. Failed queries are never charged.

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

## Pricing

from $2.00 / 1,000 trend queries

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 (Reliable)

Get Google Trends data for many keywords in one run: **interest over time, interest by region, related queries (top and rising)**, plus related topics when Google provides them. You can compare up to 5 terms in a single chart. It works with any country or region and any time range, from the past hour to 2004–present, across Web, YouTube, News, Images and Shopping search.

Built for reliability. Each query gets a fresh IP session. When Google rate limits it, the query is retried with backoff and steps up to residential IPs if needed, keeping any sections that already succeeded. The actor also slows down on its own if Google starts blocking. A failed query is reported in the dataset and **never charged**.

### Why this actor

- **Batch-friendly pricing.** You pay per query that returns data, plus a tiny start fee, so 1,000 keywords in one run cost about $2. A single-keyword call costs about 2 cents.
- **Fast.** It calls Google Trends' own JSON endpoints instead of loading a browser. Most queries finish in a few seconds.
- **Complete.** Timeline, subregions, related queries (top and rising) and related topics.
- **Honest billing.** Errors, queries where Google returns no data, and empty extra sections aren't charged. Runs stop cleanly at your max charge limit.

### Input

| Field | Example | Notes |
|---|---|---|
| `searchTerms` | `["air fryer", "iphone, samsung galaxy"]` | One query per line. Separate up to 5 terms with commas to compare them. |
| `geo` | `US`, `GB`, `US-CA` | Leave empty for worldwide. Case doesn't matter. |
| `timeRange` | `today 12-m` | Presets, or a custom `"2024-01-01 2024-06-30"` via the API (real dates from 2004-01-01). |
| `sections` | `["relatedQueries"]` | Extra sections: `interestByRegion`, `relatedQueries`, `relatedTopics`. Interest over time is always included. |
| `property` | `web`, `youtube`, `news`, `images`, `shopping` | Which search vertical to use. |
| `category` | `0` | Google Trends category ID. |
| `maxConcurrency` | `5` | Parallel queries (1–20). Lowered automatically under rate limiting. |
| `maxRetries` / `queryTimeoutSecs` | `6` / `300` | Retry budget and time limit per query. |

### Output (one item per query)

```json
{
  "searchTerm": "iphone, samsung galaxy",
  "keywords": ["iphone", "samsung galaxy"],
  "geo": "US",
  "timeRange": "today 12-m",
  "interestOverTime": [{ "date": "2025-11-02T00:00:00.000Z", "formattedTime": "Nov 2 – 8, 2025", "isPartial": false, "values": { "iphone": 51, "samsung galaxy": 3 } }],
  "interestByRegion": [{ "geoCode": "US-WY", "geoName": "Wyoming", "values": { "iphone": 79, "samsung galaxy": 18 } }],
  "relatedQueries": { "iphone": { "top": [{ "query": "iphone 17", "value": 100 }], "rising": [{ "query": "iphone 17 pro max", "value": 4250, "formattedValue": "+4,250%" }] } },
  "scrapedAt": "2026-11-01T20:02:30.000Z"
}
```

Per-keyword numbers are under `values`, keyed by the search term. Values follow Google's 0–100 relative interest scale. Rising values are percentage growth ("Breakout" means more than +5000%).

### Pricing (pay per event)

- **Actor start**: $0.02 per run.
- **Trend query** ($0.002): one per search term, or per comparison group, that returns interest-over-time data. Includes interest over time.
- **Extra section** ($0.001): one per additional section (region, related queries, related topics) that returned data.

### Notes

- **Rising queries are filtered for decoys.** Google sometimes slips generic, unrelated "rising" queries (for example "learn golang" or "best vpn service" for *protein powder*) into results for automated traffic. They change on every request. The actor drops rising queries that share no meaningful word with the keyword or its top queries, and reports how many it removed in `risingRemoved`. Top queries and interest over time aren't affected. So when Google poisons a list, you get fewer rising queries, not fake ones.
- **Related topics:** Google currently returns no related topics through its data feed for almost all queries (0 of 1,000 in our November 2026 test). The section stays available and is never charged when empty. Use related queries for keyword research.
- Very low-volume terms may return all zeros. That's Google's data, so it's delivered and charged as normal. If Google returns no timeline at all, the item has a `note` and isn't charged.
- A failed query has an `error` field. Common causes are persistent rate limiting or a query Google rejects (for example an invalid category).
- Use it via the API, on a schedule, or from AI agents through the Apify MCP server.

### Use cases

SEO and content planning, product research, seasonality forecasting, market sizing, brand comparison, and trend alerts for newsletters and dashboards.

### Use it from Python or JavaScript

Coming from pytrends? [google-trends-api](https://github.com/carterprice2/google-trends-api) is an open-source client (MIT) with a drop-in `TrendReq` that calls this actor:

```python
from google_trends_api import TrendReq   # was: from pytrends.request import TrendReq
pytrends = TrendReq()
pytrends.build_payload(["chatgpt", "gemini"], timeframe="today 3-m", geo="US")
pytrends.interest_over_time()
```

### Pair it with

- [Google Trending Now Scraper](https://apify.com/seodatalab/google-trending-now): what people are searching for right now, with search volume, by country.
- [Google Ads Transparency Scraper](https://apify.com/seodatalab/google-ads-transparency-scraper): every Google and YouTube ad a brand runs, with ad copy and landing pages.

# Actor input Schema

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

One query per line. To compare up to 5 terms on one chart, separate them with commas, e.g. "iphone, samsung galaxy".

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

ISO code such as US, GB, DE or US-CA (case doesn't matter). Leave empty for worldwide.

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

Pick a preset, or type a custom range as "YYYY-MM-DD YYYY-MM-DD", e.g. "2024-01-01 2024-06-30" (real dates, 2004-01-01 or later).

## `sections` (type: `array`):

Interest over time is always included and covered by the base price. Each extra section that returns data is charged separately.

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

Which Google search vertical to measure.

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

Google Trends category ID (0 = all categories).

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

Maximum parallel queries. The actor lowers this automatically when Google starts rate limiting.

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

Each retry uses a fresh IP session. Sections that already succeeded are kept.

## `queryTimeoutSecs` (type: `integer`):

A query that hasn't finished in this time is reported as failed (not charged).

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

Leave on automatic for the recommended setup: fast datacenter IPs with automatic fallback to residential IPs when Google rate limits. Choosing specific proxy groups, a country or your own proxy URLs uses those for every attempt. "No proxy" connects directly (not recommended).

## `saveRaw` (type: `boolean`):

Stores raw Google responses in the key-value store for debugging.

## Actor input object example

```json
{
  "searchTerms": [
    "air fryer",
    "iphone, samsung galaxy"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "sections": [
    "interestOverTime"
  ],
  "property": "web",
  "category": 0,
  "maxConcurrency": 5,
  "maxRetries": 6,
  "queryTimeoutSecs": 300,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "saveRaw": false
}
```

# Actor output Schema

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

Dataset items, one per query, with the overview view selected.

## `stats` (type: `string`):

JSON record with counts of successful, no-data and failed queries, retries, proxy tiers used and bandwidth.

# 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": [
        "air fryer",
        "iphone, samsung galaxy"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("seodatalab/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": [
        "air fryer",
        "iphone, samsung galaxy",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("seodatalab/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": [
    "air fryer",
    "iphone, samsung galaxy"
  ]
}' |
apify call seodatalab/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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