# Google Trends Scraper — Reliable (`blubberstick/google-trends-scraper`) Actor
Scrape Google Trends without 429 failures: interest over time, interest by region, related queries, related topics, and trending searches. HTTP-only (no browser) — fast and cheap.
- **URL**: https://apify.com/blubberstick/google-trends-scraper.md
- **Developed by:** [William Fordyce](https://apify.com/blubberstick) (community)
- **Categories:** SEO tools, Marketing, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet
## Pricing
from $5.00 / 1,000 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use 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 — Reliable
A **Google Trends scraper** built for one thing above all: **finishing every run**. Get **interest over time**, interest by region, **related queries**, related topics, and real-time **trending searches** as clean JSON — without a browser, without an official **Google Trends API**, and without the rate-limit failures that plague other Trends actors.
### Why this scraper succeeds where others fail
Google aggressively rate-limits its internal Trends endpoints (HTTP 429). Most Google Trends scrapers treat a 429 as fatal — that's why they fail a large share of runs. This actor was engineered around that exact failure mode:
- **Automatic session refresh** — on every 429, the cookie session is discarded and a fresh one is bootstrapped, so Google's per-session throttle resets.
- **Proxy session rotation** — when running with Apify residential proxies (the default), every retry comes from a brand-new IP session.
- **Exponential backoff with jitter** — retries start at ~2 s and back off up to 60 s, with randomized pacing between requests so you never trip the limiter in the first place.
- **Request batching** — up to 5 keywords share a single Google request (5× fewer requests = faster, cheaper, and far below the rate-limit radar).
- **Per-term fault isolation** — one bad keyword never kills your run. Failures are recorded as `dataType: "error"` items and the rest of your keywords still deliver.
- **HTTP-only, no headless browser** — runs in 256–512 MB of memory and finishes in seconds, not minutes.
### What data you get
| Data type | Description |
|---|---|
| **Interest over time** | The 0–100 search-interest timeseries for each keyword — the core Google Trends chart, ideal for keyword research and demand forecasting. |
| **Interest by region** | Search interest broken down by country, state, or metro for each keyword. |
| **Related queries** | Top and rising search queries related to each keyword — a goldmine for SEO research and content ideation. |
| **Related topics** | Top and rising Knowledge-Graph topics related to each keyword. |
| **Trending searches (now)** | What's trending in any country right now, with approximate traffic and linked news headlines. |
### Input
| Field | Type | Default | Description |
|---|---|---|---|
| `searchTerms` | array | `[]` | Keywords to scrape (max 50 per run). |
| `geo` | string | `""` (worldwide) | Location, e.g. `US`, `US-TX`, `GB`, `DE`. |
| `timeRange` | enum | `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`. |
| `category` | integer | `0` (all) | Google Trends category ID (the `cat` URL parameter on trends.google.com). |
| `includeInterestOverTime` | boolean | `true` | Scrape the interest-over-time timeseries. |
| `includeInterestByRegion` | boolean | `false` | Scrape the geographic breakdown. |
| `includeRelatedQueries` | boolean | `false` | Scrape top + rising related queries. |
| `includeRelatedTopics` | boolean | `false` | Scrape top + rising related topics. |
| `trendingNow` | boolean | `false` | Fetch current trending searches. |
| `trendingNowGeo` | string | `US` | Country for trending searches. |
| `batchTerms` | boolean | `true` | Batch up to 5 terms per Google request (faster + cheaper; values are cross-normalized for direct comparison). Turn off for solo per-term 0–100 normalization. |
| `proxyConfiguration` | object | Apify residential | Proxy settings. Residential strongly recommended. |
Example input:
```json
{
"searchTerms": ["coffee", "matcha"],
"geo": "US",
"timeRange": "today 12-m",
"includeInterestOverTime": true,
"includeRelatedQueries": true,
"trendingNow": true
}
````
### Output
One dataset item per keyword per data type: `{ term, geo, timeRange, dataType, data, fetchedAt }`.
**Interest over time** (`dataType: "interestOverTime"`):
```json
{
"term": "coffee",
"geo": "US",
"timeRange": "today 12-m",
"dataType": "interestOverTime",
"data": [
{ "time": 1749340800, "formattedTime": "Jun 8 – 14, 2025", "value": 62 },
{ "time": 1780790400, "formattedTime": "Jun 7 – 13, 2026", "value": 73, "isPartial": true }
],
"fetchedAt": "2026-06-10T21:03:51.347Z"
}
```
**Related queries** (`dataType: "relatedQueries"`):
```json
{
"term": "matcha",
"dataType": "relatedQueries",
"data": [
{ "query": "matcha latte", "value": 100, "formattedValue": "100", "trend": "top", "link": "https://trends.google.com/trends/explore?q=matcha+latte&date=today+12-m&geo=US" },
{ "query": "matcha near me", "value": 130, "formattedValue": "+130%", "trend": "rising", "link": "..." }
]
}
```
**Interest by region** (`dataType: "interestByRegion"`):
```json
{
"term": "bitcoin",
"dataType": "interestByRegion",
"data": [
{ "geoCode": "US-WY", "geoName": "Wyoming", "value": 100 },
{ "geoCode": "US-CA", "geoName": "California", "value": 71 }
]
}
```
**Trending searches** (`dataType: "trendingNow"`):
```json
{
"dataType": "trendingNow",
"geo": "US",
"data": [
{
"title": "tornado warning",
"approxTraffic": "50000+",
"pubDate": "Wed, 10 Jun 2026 13:30:00 -0700",
"newsItems": [
{ "title": "EF-1 Tornado Confirmed In Freeland", "url": "https://...", "source": "WNEM" }
]
}
]
}
```
If a keyword fails after all retries, you get an item with `dataType: "error"` and an `error` message — the run continues and still succeeds for the other keywords.
### Pricing (pay per event)
You only pay for data you actually receive — **empty results are never charged**:
| Event | Charged when | Suggested price |
|---|---|---|
| `term-result` | One keyword × one data type returns non-empty data | $0.003 |
| `trending-now-fetch` | One trending-searches fetch returns entries | $0.02 |
Example: 10 keywords with interest over time + related queries = 20 `term-result` events ≈ **$0.06**.
### FAQ
**Is it legal to scrape Google Trends?**
Yes. Google Trends data is public, aggregated, and anonymized — there is no personal data involved. This actor only accesses the same public endpoints your browser uses on trends.google.com. As always, consult your own counsel for your specific use case.
**How is this different from other Google Trends actors?**
Reliability. Other Trends scrapers fail a significant share of runs because they treat Google's 429 rate-limit responses as fatal errors. This actor was engineered around that failure mode from day one: session refresh, residential proxy rotation, exponential backoff, request batching, and per-keyword fault isolation. One bad keyword or one throttled request never costs you the run.
**Is there an official Google Trends API?**
Google has only an invite-limited alpha API. For everyone else, scraping the public website data is the only way to get interest over time, related queries, and trending searches programmatically — this actor does it for you and returns clean JSON.
**Why are my related topics sometimes empty?**
Google gates topic (Knowledge Graph entity) data behind a stricter per-IP quota than the other data types. The actor automatically retries topics through a secondary endpoint with its own quota; if Google still withholds the data, you get an empty list — and you are not charged for it.
**Can I monitor keywords on a schedule?**
Yes — add the actor to an Apify Schedule (e.g. daily) and connect a webhook or one of Apify's integrations (Google Sheets, Slack, Make, Zapier) to deliver fresh keyword-research data automatically.
**What are the values in interest over time?**
Google's normalized search-interest index: 100 = peak popularity within your selected time range and location, 50 = half as popular. Values are relative, not absolute search volumes. With the default `batchTerms: true`, terms scraped together share one scale (directly comparable, exactly like comparing terms on trends.google.com). Set `batchTerms: false` to give every term its own 0–100 scale relative to its own peak — recommended when mixing high- and low-volume keywords.
### Tips
- Batch related keywords in a single run — the actor groups up to 5 per Google request, so 50 keywords cost only ~10 explore calls.
- Use `geo` + `timeRange` combinations that match what you'd select on trends.google.com; sub-regions like `US-TX` work everywhere.
- For SEO research, enable `includeRelatedQueries` — rising queries (`"trend": "rising"`) surface breakout searches before they peak.
# Actor input Schema
## `searchTerms` (type: `array`):
Keywords to query on Google Trends, e.g. coffee, bitcoin price. Up to 50 per run. Terms are batched 5 per request for speed and reliability. Leave empty if you only want trending searches.
## `geo` (type: `string`):
Two-letter country code, optionally with a region, e.g. US, US-TX, GB, DE. Leave empty for worldwide.
## `timeRange` (type: `string`):
Period to scrape data for. Matches the time-range picker on the Google Trends website.
## `category` (type: `integer`):
Google Trends category ID to narrow results (0 = all categories). Find IDs in the cat URL parameter on trends.google.com, e.g. 71 = Food & Drink, 7 = Finance.
## `includeInterestOverTime` (type: `boolean`):
Scrape the interest-over-time timeseries (0–100 index) for each search term.
## `includeInterestByRegion` (type: `boolean`):
Scrape the geographic breakdown (interest score per country or per sub-region of the selected location).
## `includeRelatedQueries` (type: `boolean`):
Scrape top and rising related search queries for each term — great for keyword research.
## `includeRelatedTopics` (type: `boolean`):
Scrape top and rising related topics (Knowledge Graph entities) for each term.
## `trendingNow` (type: `boolean`):
Fetch the list of searches currently trending in the selected country (real-time, with approximate traffic and related news headlines).
## `trendingNowGeo` (type: `string`):
Country code for trending searches, e.g. US, GB, JP.
## `batchTerms` (type: `boolean`):
When on (default), up to 5 terms share one Google request — 5× faster and cheaper, and interest values are cross-normalized so terms are directly comparable (like comparing them on trends.google.com). Turn off to query each term separately, so every term gets its own 0–100 scale relative to its own peak (better precision for low-volume terms).
## `proxyConfiguration` (type: `object`):
Proxies to use. Residential proxies (default) are strongly recommended — Google rate-limits datacenter IP ranges aggressively. The actor automatically rotates to a fresh proxy session whenever Google rate-limits a request.
## Actor input object example
```json
{
"searchTerms": [
"coffee",
"matcha"
],
"geo": "US",
"timeRange": "today 12-m",
"category": 0,
"includeInterestOverTime": true,
"includeInterestByRegion": false,
"includeRelatedQueries": false,
"includeRelatedTopics": false,
"trendingNow": false,
"trendingNowGeo": "US",
"batchTerms": true,
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}
```
# 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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"searchTerms": [
"coffee",
"matcha"
],
"geo": "US",
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
};
// Run the Actor and wait for it to finish
const run = await client.actor("blubberstick/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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"searchTerms": [
"coffee",
"matcha",
],
"geo": "US",
"proxyConfiguration": {
"useApifyProxy": True,
"apifyProxyGroups": ["RESIDENTIAL"],
},
}
# Run the Actor and wait for it to finish
run = client.actor("blubberstick/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 '{
"searchTerms": [
"coffee",
"matcha"
],
"geo": "US",
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}' |
apify call blubberstick/google-trends-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=blubberstick/google-trends-scraper",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Google Trends Scraper — Reliable",
"description": "Scrape Google Trends without 429 failures: interest over time, interest by region, related queries, related topics, and trending searches. HTTP-only (no browser) — fast and cheap.",
"version": "0.1",
"x-build-id": "NPA0VgAtFCBRV1RXW"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/blubberstick~google-trends-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-blubberstick-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/blubberstick~google-trends-scraper/runs": {
"post": {
"operationId": "runs-sync-blubberstick-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/blubberstick~google-trends-scraper/run-sync": {
"post": {
"operationId": "run-sync-blubberstick-google-trends-scraper",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"properties": {
"searchTerms": {
"title": "Search terms",
"uniqueItems": true,
"type": "array",
"description": "Keywords to query on Google Trends, e.g. coffee, bitcoin price. Up to 50 per run. Terms are batched 5 per request for speed and reliability. Leave empty if you only want trending searches.",
"items": {
"type": "string"
}
},
"geo": {
"title": "Location (geo)",
"type": "string",
"description": "Two-letter country code, optionally with a region, e.g. US, US-TX, GB, DE. Leave empty for worldwide.",
"default": ""
},
"timeRange": {
"title": "Time range",
"enum": [
"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"
],
"type": "string",
"description": "Period to scrape data for. Matches the time-range picker on the Google Trends website.",
"default": "today 12-m"
},
"category": {
"title": "Category",
"minimum": 0,
"type": "integer",
"description": "Google Trends category ID to narrow results (0 = all categories). Find IDs in the cat URL parameter on trends.google.com, e.g. 71 = Food & Drink, 7 = Finance.",
"default": 0
},
"includeInterestOverTime": {
"title": "Interest over time",
"type": "boolean",
"description": "Scrape the interest-over-time timeseries (0–100 index) for each search term.",
"default": true
},
"includeInterestByRegion": {
"title": "Interest by region",
"type": "boolean",
"description": "Scrape the geographic breakdown (interest score per country or per sub-region of the selected location).",
"default": false
},
"includeRelatedQueries": {
"title": "Related queries",
"type": "boolean",
"description": "Scrape top and rising related search queries for each term — great for keyword research.",
"default": false
},
"includeRelatedTopics": {
"title": "Related topics",
"type": "boolean",
"description": "Scrape top and rising related topics (Knowledge Graph entities) for each term.",
"default": false
},
"trendingNow": {
"title": "Trending searches now",
"type": "boolean",
"description": "Fetch the list of searches currently trending in the selected country (real-time, with approximate traffic and related news headlines).",
"default": false
},
"trendingNowGeo": {
"title": "Trending searches location",
"type": "string",
"description": "Country code for trending searches, e.g. US, GB, JP.",
"default": "US"
},
"batchTerms": {
"title": "Batch terms (comparison mode)",
"type": "boolean",
"description": "When on (default), up to 5 terms share one Google request — 5× faster and cheaper, and interest values are cross-normalized so terms are directly comparable (like comparing them on trends.google.com). Turn off to query each term separately, so every term gets its own 0–100 scale relative to its own peak (better precision for low-volume terms).",
"default": true
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Proxies to use. Residential proxies (default) are strongly recommended — Google rate-limits datacenter IP ranges aggressively. The actor automatically rotates to a fresh proxy session whenever Google rate-limits a request.",
"default": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```