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

Bulk Google Trends data: interest over time, interest by region, related queries and topics. Multi-keyword comparison, any country, any timeframe. Proxy-backed to beat rate limits.

- **URL**: https://apify.com/f-keys/google-trends-scraper.md
- **Developed by:** [Vince Gonzalez](https://apify.com/f-keys) (community)
- **Categories:** SEO tools, News, AI
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Trends Scraper

Pull Google Trends data at scale: **interest over time**, **interest by region**, **related queries**, and **related topics** — for any keyword, any country, any timeframe, with multi-keyword comparison. Proxy-backed so it keeps working where lighter scrapers get rate-limited.

Built for market researchers, SEO teams, trend analysts, and anyone tracking demand signals without clicking through the Trends UI one query at a time.

***

### What it does

- **Four data types**, pick any combination per run: interest over time, interest by region, related queries, related topics.
- **Multi-keyword comparison.** Put up to five comma-separated keywords in one entry and get them on the same 0–100 scale, exactly like the Trends comparison view.
- **Any geography and timeframe.** Worldwide or down to a sub-region; last hour to the full history.
- **Built for Google's rate limits.** Google Trends returns `429 Too Many Requests` to datacenter IPs almost immediately — the single biggest reason bulk Trends scraping fails. This actor retries with backoff, rotates to a fresh proxy session on each attempt, and is tuned to run at safe concurrency by default. Use residential proxies for the most reliable results.

### Input

| Field | Type | Description |
|---|---|---|
| `searchTerms` | array (required) | One entry per query. `"coffee"` is a single query; `"python, javascript, rust"` is one comparison group (max 5). |
| `geo` | string | Country/region code (`US`, `GB`, `DE`, `US-CA`). Empty = worldwide. |
| `timeRange` | string | `now 7-d`, `today 3-m`, `today 12-m`, `today 5-y`, `all`, or `2024-01-01 2024-12-31`. |
| `dataTypes` | array | Any of `interestOverTime`, `interestByRegion`, `relatedQueries`, `relatedTopics`. |
| `category` | integer | Google category ID (0 = all). |
| `tz` | integer | Timezone offset in minutes (default 360). |
| `concurrency` | integer | Parallel terms, 1–8. Keep low (2–3) unless using strong residential proxies. |
| `maxRetries` | integer | Retries per term; 429s back off and rotate proxy session. |
| `proxyConfiguration` | object | Apify Proxy recommended; residential is best for Trends. |

#### Example input

```json
{
  "searchTerms": ["coffee", "python, javascript, rust"],
  "geo": "US",
  "timeRange": "today 12-m",
  "dataTypes": ["interestOverTime", "relatedQueries"],
  "proxyConfiguration": { "useApifyProxy": true, "groups": ["RESIDENTIAL"] }
}
```

### Output

One dataset row per search term.

```json
{
  "searchTerm": "coffee",
  "keywords": ["coffee"],
  "geo": "US",
  "time": "today 12-m",
  "status": "ok",
  "interestOverTime": [
    { "date": "Aug 23 – 29, 2026", "timestamp": 1787443200, "coffee": 71, "isPartial": true }
  ],
  "relatedQueries": {
    "top": [
      { "query": "coffee near me", "value": 100, "formattedValue": "100", "link": "https://trends.google.com/..." }
    ],
    "rising": [
      { "query": "...", "value": 250, "formattedValue": "+250%", "link": "..." }
    ]
  }
}
```

For a comparison group, each keyword becomes its own column in every `interestOverTime` / `interestByRegion` row.

**`status`** is `ok` or `error` (with an `error` field — usually a persistent `429` when proxies are exhausted, or an invalid geo/time).

### Pricing

Pay-per-event: charged only per search term that returns successfully (`status = "ok"`). Failed terms cost nothing.

### Notes & limits

- Google Trends values are **relative** (0–100), not absolute search counts — that's how Trends itself works, not a limit of the actor.
- The most recent bucket is often marked `isPartial` because the period hasn't closed yet.
- Residential proxies dramatically improve success rates versus datacenter IPs.
- This actor reads publicly available Google Trends data. Use the output in accordance with Google's Terms of Service and applicable law in your jurisdiction.

### Running locally (developers)

```
npm install
npm test
```

`src/test-local.js` calls the live endpoints with no proxy, so it may report `429` from a datacenter IP — that is expected and is exactly what proxies solve in production. The extraction logic lives in `src/trends.js` with no dependency on the Apify SDK.

***

www.f-keys.com | © 2026 F-Keys Creative LLC

# Actor input Schema

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

One entry per query. A single keyword (e.g. "coffee") is queried on its own. A comma-separated entry (e.g. "python, javascript, rust") is compared as one group — Google compares up to 5 terms at once.

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

ISO country code (US, GB, DE, JP) or a sub-region (US-CA, GB-ENG). Leave empty for worldwide.

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

Google Trends time expression: 'now 1-H', 'now 7-d', 'today 1-m', 'today 3-m', 'today 12-m', 'today 5-y', 'all', or a custom range like '2024-01-01 2024-12-31'.

## `dataTypes` (type: `array`):

Which Trends datasets to pull for each term.

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

Google Trends category filter (0 = all categories). See Google's category list for IDs.

## `tz` (type: `integer`):

Minutes offset used for time buckets. 360 = US Central. Leave as default unless you need a specific timezone.

## `concurrency` (type: `integer`):

Terms processed in parallel (1-8). Google Trends rate-limits hard — keep this low (2-3) unless you have strong residential proxies.

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

Retries on failure. Rate-limit (429) hits back off and rotate to a fresh proxy session.

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

STRONGLY recommended. Google Trends returns 429 to datacenter IPs quickly; residential proxies (Apify Proxy RESIDENTIAL group) are the most reliable.

## Actor input object example

```json
{
  "searchTerms": [
    "coffee",
    "python, javascript, rust"
  ],
  "geo": "",
  "timeRange": "today 12-m",
  "dataTypes": [
    "interestOverTime"
  ],
  "category": 0,
  "tz": 360,
  "concurrency": 2,
  "maxRetries": 4,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `trends` (type: `string`):

The scraped Google Trends data, as JSON dataset items.

# 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",
        "python, javascript, rust"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("f-keys/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",
        "python, javascript, rust",
    ],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("f-keys/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",
    "python, javascript, rust"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call f-keys/google-trends-scraper --silent --output-dataset

```

## MCP server setup

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