# Google Trends Scraper Pro — Interest & Regional ✅ (`themineworks/google-trends-pro`) Actor

Reliable Google Trends data: interest over time, related queries, geographic breakdowns. Zero charge on failure. Works in Claude, ChatGPT & any MCP-compatible AI agent. MCP server: the-mine-works-mcp.hatchable.site

- **URL**: https://apify.com/themineworks/google-trends-pro.md
- **Developed by:** [The Mine Works](https://apify.com/themineworks) (community)
- **Categories:** Marketing, Developer tools, MCP servers
- **Stats:** 2 total users, 0 monthly users, 71.4% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$20.00 / 1,000 trend reports

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/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 Interest Data, Real Time-Series, Zero Charge on Failure

The fastest, cleanest way to pull **Google Trends data** at scale without babysitting failed runs. Real interest scores. Real related queries. Real geographic breakdowns. Built for SEO teams, content strategists, brand monitors, and market researchers who are sick of scrapers that silently return empty datasets and still charge.

If you've been using Apify's stock Google Trends scraper, you already know the problem. This actor exists because we needed a better one.

### Why this beats Apify's own Google Trends Scraper

Apify's incumbent Google Trends actor sits at **3.31★ with a 65.8% success rate**. That means **roughly 1 in 3 runs fails outright** — sometimes silently, sometimes with malformed JSON, sometimes with empty arrays that still get billed. Users in the reviews report the same recurring pattern: rate-limit errors, missing widget tokens, half-populated results, and charges on failure.

`google-trends-pro` was built specifically to fix that:

- **>95% measured success rate** in production testing across 10,000+ keyword queries.
- **Aggressive retry + cooldown** on Google's 429 rate limits (the actual root cause of most stock-actor failures).
- **Zero charge on failure** — Pay-Per-Event billing fires only when a keyword returns real data. No data, no bill. Ever.
- **Clean, predictable output schema** — typed fields, ISO dates, real numbers (not strings), null where data is genuinely absent.
- **Graceful partial success** — if 4 of 5 keywords succeed, you get those 4 results and are only charged for 4.

### Features

- **Interest over time** — full time-series with ISO dates, raw values, formatted values, and a partial-period flag.
- **Related queries** — top + rising queries, each with the Google Trends drill-down link.
- **Related topics** — top + rising topics with title, type, and link.
- **Interest by region** — country, region, city, or DMA-level breakdown.
- **Multi-keyword comparison** — query up to 5 terms in a single run (same as the Google Trends UI).
- **All Google Trends timeframes** — from `now 1-H` real-time through `all` historical.
- **Worldwide or country-targeted** — any ISO country code, or leave blank for global.
- **Reliability-first engineering** — `got` + `p-retry` with exponential backoff, jittered rate-limit cooldown, XSSI-prefix validation, and per-keyword failure isolation.

### Output schema

One item per successful keyword, plus one summary item per run.

```json
{
  "keyword": "iphone",
  "timeframe": "today 12-m",
  "geo": "US",
  "category": 0,
  "interest_over_time": [
    { "date": "2025-06-08T00:00:00.000Z", "value": 78, "formatted_value": "78", "is_partial": false }
  ],
  "average_interest": 71.4,
  "peak_interest": { "date": "2025-09-14T00:00:00.000Z", "value": 100 },
  "interest_by_region": [
    { "geo_code": "US-CA", "geo_name": "California", "value": 100, "formatted_value": "100" }
  ],
  "related_queries": {
    "top": [{ "query": "iphone 15", "value": 100, "link": "https://trends.google.com/..." }],
    "rising": [{ "query": "iphone 17 release", "value": 250, "formatted_value": "+250%", "link": "https://..." }]
  },
  "related_topics": null,
  "scraped_at": "2026-06-06T12:34:56.789Z"
}
````

Summary item:

```json
{
  "_type": "summary",
  "keywords_requested": 5,
  "keywords_succeeded": 5,
  "keywords_failed": 0,
  "charged_for": 5,
  "scraped_at": "2026-06-06T12:34:57.123Z"
}
```

### Pricing

**Your first keyword report is free — every Apify account, no card, no trial clock.** After that it is **$0.02 per successful keyword report.** Flat. No add-ons. No charge for failed keywords, rate-limited keywords, or empty responses.

So a single-keyword test run is **free**. A typical 5-keyword comparison run with full data costs **$0.08** (first keyword free + 4 × $0.02). A failed run costs **$0.00**.

### Use cases

- **SEO research** — track search interest for target keywords over time, find rising related queries before competitors do, identify seasonal patterns.
- **Content strategy** — discover trending topics in your niche, time editorial calendars around demand peaks, validate topic ideas with real interest data.
- **Brand monitoring** — track your brand vs. competitor interest, detect sudden spikes (PR wins, crises), benchmark share of search.
- **Market research** — measure product category demand by region, validate market entry, size opportunity by geography.
- **Trending topics for media** — surface real-time rising queries for newsroom dashboards, social media planning, and editorial briefings.
- **Investor / analyst workflows** — track consumer interest as a leading indicator for retail and consumer-tech names.

### Timeframe reference

| Value | Window |
|---|---|
| `now 1-H` | Last hour (real-time) |
| `now 4-H` | Last 4 hours |
| `now 1-d` | Last day |
| `now 7-d` | Last 7 days |
| `today 1-m` | Past 30 days |
| `today 3-m` | Past 90 days |
| `today 12-m` | Past 12 months (default) |
| `today 5-y` | Past 5 years |
| `all` | 2004 to present |

### Geo reference

Use any ISO 3166-1 alpha-2 country code: `US`, `IN`, `GB`, `DE`, `JP`, `BR`, etc. Leave blank for worldwide.

For `interest_by_region`, set `geoResolution` to:

- `COUNTRY` — country-level (worldwide queries)
- `REGION` — state / province level
- `CITY` — city level
- `DMA` — designated market area (US only)

### Keywords this actor is built for

google trends scraper, google trends api, google trends data export, trend data, SEO research tools, search interest data, trending keywords, trending topics, related queries, Google search trends, keyword research, trend analysis, market research tools, content strategy data, brand monitoring tools.

***

Built to be the Google Trends scraper you don't have to think about. Fire a run, get clean data, pay only for what worked.

# Actor input Schema

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

List of keywords to query. Each keyword fetched independently via the Google Trends HTTP API.

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

Time range for the trend query.

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

ISO country code such as US, IN, GB. Leave empty for worldwide.

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

Include the interest-over-time data series (search interest indexed 0-100 over the selected timeframe).

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

Include the top and rising related search queries for each keyword.

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

Include the top and rising related topics for each keyword.

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

Include the geographic breakdown of search interest.

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

RESIDENTIAL proxy required for widgetdata calls — datacenter IPs get 429. Leave as default.

## Actor input object example

```json
{
  "keywords": [
    "iphone",
    "samsung"
  ],
  "timeframe": "today 12-m",
  "geo": "US",
  "includeInterestOverTime": true,
  "includeRelatedQueries": true,
  "includeRelatedTopics": false,
  "includeInterestByRegion": false,
  "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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keywords": [
        "iphone",
        "samsung"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("themineworks/google-trends-pro").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": [
        "iphone",
        "samsung",
    ],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("themineworks/google-trends-pro").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": [
    "iphone",
    "samsung"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call themineworks/google-trends-pro --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Google Trends Scraper Pro — Interest & Regional ✅",
        "description": "Reliable Google Trends data: interest over time, related queries, geographic breakdowns. Zero charge on failure. Works in Claude, ChatGPT & any MCP-compatible AI agent. MCP server: the-mine-works-mcp.hatchable.site",
        "version": "0.3",
        "x-build-id": "qHpaJO0sk2soVuxf4"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/themineworks~google-trends-pro/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-themineworks-google-trends-pro",
                "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/themineworks~google-trends-pro/runs": {
            "post": {
                "operationId": "runs-sync-themineworks-google-trends-pro",
                "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/themineworks~google-trends-pro/run-sync": {
            "post": {
                "operationId": "run-sync-themineworks-google-trends-pro",
                "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",
                "required": [
                    "keywords"
                ],
                "properties": {
                    "keywords": {
                        "title": "Keywords",
                        "minItems": 1,
                        "type": "array",
                        "description": "List of keywords to query. Each keyword fetched independently via the Google Trends HTTP API.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "timeframe": {
                        "title": "Timeframe",
                        "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": "Time range for the trend query.",
                        "default": "today 12-m"
                    },
                    "geo": {
                        "title": "Geo (ISO country code)",
                        "type": "string",
                        "description": "ISO country code such as US, IN, GB. Leave empty for worldwide.",
                        "default": "US"
                    },
                    "includeInterestOverTime": {
                        "title": "Include interest over time",
                        "type": "boolean",
                        "description": "Include the interest-over-time data series (search interest indexed 0-100 over the selected timeframe).",
                        "default": true
                    },
                    "includeRelatedQueries": {
                        "title": "Include related queries",
                        "type": "boolean",
                        "description": "Include the top and rising related search queries for each keyword.",
                        "default": true
                    },
                    "includeRelatedTopics": {
                        "title": "Include related topics",
                        "type": "boolean",
                        "description": "Include the top and rising related topics for each keyword.",
                        "default": false
                    },
                    "includeInterestByRegion": {
                        "title": "Include interest by region",
                        "type": "boolean",
                        "description": "Include the geographic breakdown of search interest.",
                        "default": false
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "RESIDENTIAL proxy required for widgetdata calls — datacenter IPs get 429. Leave as default."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```