# Google Trends Scraper — Related Queries, Regions & Comparison (`leorochasantos/google-trends-scraper`) Actor

Fast, reliable Google Trends data: interest over time, related queries, multi-term comparison, and interest by region. Clean flat JSON built for LLM/MCP consumption.

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

## Pricing

from $5.00 / 1,000 keyword results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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 — Fast, Reliable, Agent-Ready

Pull **Google Trends** data through a clean JSON API: interest over time, related search
queries, multi-keyword comparison, and interest by region. Built HTTP-first (no slow
headless browser), with automatic proxy rotation and retries so runs **don't hang and
don't come back empty**.

> Designed for people who got burned by scrapers that "run for 20 minutes and return
> nothing." Every field is typed, flat, and ready to drop straight into an LLM, an MCP
> tool, a dashboard, or a spreadsheet.

### Why this one

- ⚡ **Fast & cheap** — internal-API path, ~6–8 s per run at 512 MB. No 4 GB Chrome.
- 🛡️ **Reliable** — each request retries on a fresh proxy IP with backoff; blocks are
  routed around, not waited on until timeout.
- 🔁 **Multi-keyword comparison** — compare up to 5 terms on Google's shared 0–100 scale
  in a single run.
- 🔎 **Related queries** — top and rising, per keyword.
- 🌍 **Interest by region** — country, region/state, city, or metro (DMA).
- 🤖 **Agent-friendly output** — values keyed by keyword (no array-of-arrays), explicit
  `data_granularity`, absolute URLs, no redundant formatted-string clutter.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `keywords` | string\[] | — | 1–5 search terms. Multiple terms are compared together. |
| `timeframe` | string | `today 12-m` | `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`. |
| `customTimeRange` | string | — | Explicit `YYYY-MM-DD YYYY-MM-DD` (overrides `timeframe`). |
| `geo` | string | `""` | Country (`US`, `BR`, `GB`), sub-region (`US-CA`), or empty for Worldwide. |
| `category` | integer | `0` | Google Trends category id (0 = all). |
| `searchProperty` | string | `""` | `""` web, `images`, `news`, `youtube`, `froogle` (Shopping). |
| `includeRelatedQueries` | boolean | `true` | Top + rising related queries per keyword. |
| `includeInterestByRegion` | boolean | `true` | Geographic breakdown per keyword. |
| `geoResolution` | string | `COUNTRY` | `COUNTRY` / `REGION` / `CITY` / `DMA`. |
| `language` | string | `en-US` | UI language for labels. |
| `proxyConfiguration` | object | Apify Proxy | **Required** — Google blocks direct datacenter IPs. |

#### Example input

```json
{
  "keywords": ["bitcoin", "ethereum"],
  "timeframe": "today 12-m",
  "geo": "US",
  "includeRelatedQueries": true,
  "includeInterestByRegion": true,
  "geoResolution": "REGION"
}
```

### Output

One dataset item per run:

```json
{
  "keywords": ["bitcoin", "ethereum"],
  "timeframe": "today 12-m",
  "geo": "US",
  "data_granularity": "week",
  "interest_over_time": [
    { "date": "2025-06-29T00:00:00.000Z", "values": { "bitcoin": 27, "ethereum": 14 }, "is_partial": false }
  ],
  "average_interest": { "bitcoin": 41, "ethereum": 19 },
  "keyword_details": [
    {
      "keyword": "bitcoin",
      "related_queries": {
        "top": [{ "query": "bitcoin price", "value": 100 }],
        "rising": [{ "query": "how to buy bitcoin safely", "value": 14250 }]
      },
      "interest_by_region": [{ "geo_code": "US-WY", "geo_name": "Wyoming", "value": 100 }]
    }
  ],
  "trends_url": "https://trends.google.com/trends/explore?q=bitcoin,ethereum&date=today%2012-m&geo=US",
  "scraped_at": "2026-07-04T16:00:00.000Z"
}
```

### Use cases

- **SEO & content** — find rising related queries before they peak.
- **Market & trend research** — compare brands/products on one normalized scale, by region.
- **Finance/crypto signals** — track search interest over time as a demand proxy.
- **LLM agents & MCP tools** — flat typed JSON that needs no post-processing.

### Notes

- **Interest values are relative (0–100)**, normalized within each run — exactly as Google
  Trends defines them, not absolute search volumes.
- **Related topics are not included.** Google withholds related-topics data from
  programmatic requests; other Google Trends actors return it empty as well. We leave it
  out rather than ship an always-empty field.
- A proxy is required. The default Apify Proxy configuration works out of the box.

### Support

Found a gap or a broken field? Open an issue on the actor page — this scraper is actively
monitored and patched.

### Pricing

Pay per event, and **the platform usage is on us** — the price you see is the price you pay, with no compute bill on top.

| Event | Price | What one charge buys |
|---|---|---|
| Keyword result | **$0.005** | One keyword's full Trends data. Only charged for keywords that return results. |
| Actor Start | **$0.004** | One run, whatever it returns. |

Higher Apify subscription tiers pay less on every event (Silver −20%, Gold −35%).

# Actor input Schema

## `keywords` (type: `array`):

Search terms to fetch trends for. Provide 1–5 terms to compare them on a single normalized 0–100 scale (Google's own comparison). Each item in a separate run is compared independently.

## `timeframe` (type: `string`):

Time window for the trend. Use a preset or supply a custom range below.

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

Optional. Explicit range as 'YYYY-MM-DD YYYY-MM-DD' (e.g. '2024-01-01 2024-06-30'). When set, Timeframe is ignored.

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

Two-letter country code (e.g. 'US', 'BR', 'GB'), a sub-region ('US-CA'), or empty for Worldwide.

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

Google Trends category id to narrow the search (0 = All categories).

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

Which Google surface to measure interest on.

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

Fetch top and rising related search queries per keyword.

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

Fetch the geographic breakdown of interest per keyword.

## `geoResolution` (type: `string`):

Granularity of the interest-by-region breakdown. COUNTRY works worldwide; REGION/CITY/DMA require a specific country in 'Region'.

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

UI language code used by Google Trends for labels (e.g. 'en-US', 'pt-BR').

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

Apify Proxy is required — Google Trends blocks direct datacenter IPs. Defaults to the automatic Apify Proxy group.

## Actor input object example

```json
{
  "keywords": [
    "web scraping"
  ],
  "timeframe": "today 12-m",
  "geo": "",
  "category": 0,
  "searchProperty": "",
  "includeRelatedQueries": true,
  "includeInterestByRegion": true,
  "geoResolution": "COUNTRY",
  "language": "en-US",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `results` (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 = {
    "keywords": [
        "web scraping"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("leorochasantos/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 = { "keywords": ["web scraping"] }

# Run the Actor and wait for it to finish
run = client.actor("leorochasantos/google-trends-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keywords": [
    "web scraping"
  ]
}' |
apify call leorochasantos/google-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=leorochasantos/google-trends-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/6ZIUtW0PicPI6knpN/builds/VwLVYfC1qmkdLhWGg/openapi.json