# Google Trends Scraper (`scraperpro/google-trends-ppe`) Actor
Extract Real-Time Trends, Historical Data, Regional Demand, and Related Queries. Native proxy rotation bypasses rate limits. Pay-per-result pricing.
- **URL**: https://apify.com/scraperpro/google-trends-ppe.md
- **Developed by:** [ScraperPro](https://apify.com/scraperpro) (community)
- **Categories:** SEO tools, E-commerce, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars
## Pricing
from $2.50 / 1,000 trend results
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 | 5-in-1 All-Inclusive Tool
[](https://apify.com/)
[](#)
[](#)
*Why pay for 5 different actors? This is the **ONLY all-in-one Google Trends solution** you need. Extract real-time trends, historical timeline data, regional maps, related queries, and topicsβall from a single, unified scraper. Bypass strict 429 rate limits natively using automated residential proxies.*
---
### π₯ The Ultimate All-in-One Intelligence Scraper
Stop paying for fragmented scrapers that only do one thing, break on unrecognized regions, or fail silently without giving you data. This Google Trends Scraper replaces multiple tools by offering **5 unique intelligence endpoints in a single actor**. Coupled with a heavily optimized **2.0 Infrastructure**, it bypasses Google's aggressive rate-limiting out of the box.
* β
**5 Unique Intelligence Endpoints**: Grab *Trending Now* (Real-Time), *Interest Over Time* (Historical), *Interest by Region*, *Related Queries*, or *Related Topics* without switching actors or paying split costs.
* β
**Native Residential Proxies**: Built-in evasion techniques guarantee zero IP blocks. (Proxy rotation included)
* β
**Enterprise Architecture**: Built by experts to handle edge cases like missing regional data, arrays, and timezone anomalies without crashing.
* β
**Big Data Ready**: Returns flat, perfectly normalized JSON directly to your datasets, fully compatible with Apify CSV, Excel, or Pandas DataFrames.
---
### π Unbeatable Pay-Per-Result ROI
We use a heavily structured **dynamic pay-per-result** model at exactly **$2.50 per 1,000 results** ($0.0025 per event). **100% Predictable Pricing: Zero unexpected compute or proxy fees!** We absorb all Apify platform costs so your billing is fully predictable.
*(To test without risk, we set the default `max_events` to 100. Feel free to lower it to `10` to verify output quality for practically zero cost!)*
#### π Quick Pricing Reference:
* **Safety Test Run** (10 items) = `$0.02`
* **Starter Run** (100 items) = `$0.25`
* **Full Historical Analytics** (1,000 items) = `$2.50`
* **Zero Risk on Failure**: If the run fails because of a bad keyword or Google error, you only pay for a single error item ($0.0025)!
---
### π οΈ Extensive Core Features
#### 1. π Trending Now (Real-time Pulses)
Monitor the exact pulse of the internet globally. Perfect for news aggregators and reactive social media marketers.
* Real-time trend scoring with hourly windows.
* Contextual news articles automatically attached.
* Precise traffic volume estimates (e.g., "5M+ Searches").
#### 2. π Interest Over Time
Extract precision timeline data spanning from 2004 to today. Great for spotting macro seasonal shifts in e-commerce or finance.
* Compare up to 5 strategic keywords simultaneously.
* Normalized scoring (0-100 search index).
#### 3. πΊοΈ Interest by Region
Reveal exactly where keyword demand is centralized geographically.
* Granular breakdowns by Country, Region (State), DMA, or City.
* Perfect for targeted local PPC advertising.
#### 4. π Related Queries & π·οΈ Related Topics
Reverse-engineer Google's contextual groupings to unearth long-tail keywords your competitors miss.
* Flags both "Rising" (breakout trends) and "Top" semantic queries.
* Extracts enriched Google Knowledge Graph entity categories.
---
### π― High-ROI Implementation Use Cases
- π **E-commerce & Dropshipping**: Identify viral products (e.g., TikTok trends) before market saturation occurs.
- π **SEO Content Planning**: Blueprint thousands of blog posts dynamically using Related Queries.
- πΈ **Algorithmic Trading**: Correlate breakout consumer search volume for specific ticker symbols with quantitative price action.
- π§βπΌ **Enterprise Market Research**: Uncover deep demographic shifts and map brand penetration.
---
### βοΈ Input Configuration Options
| Parameter | Description |
| --------- | ----------- |
| `scrape_type` | Choice of 5 endpoints (e.g., `trending_now`, `interest_over_time`). |
| `keywords` | Up to 5 target queries (Required for historical modes). |
| `predefined_timeframe`| Fast dropdowns like `today 12-m`, `now 7-d`, or `all`. |
| `gprop` | Service filter: Web, Images, News, Shopping, YouTube. |
| `geo_resolution`| Precision level: `COUNTRY`, `REGION`, `CITY`, or `DMA`. |
---
### π Clean, Normalized JSON Output
Every run outputs perfectly serialized, cross-platform friendly data.
π₯ Input Example (JSON)
```json
{
"scrape_type": "interest_over_time",
"keywords": [
"Web scraping",
"Data extraction"
],
"timeframe_type": "predefined",
"predefined_timeframe": "today 12-m",
"geo_selection_type": "Common Countries",
"common_geo": "US",
"max_events": 100
}
````
π Output Example: Interest Over Time
```json
{
"scrape_type": "interest_over_time",
"event_index": 1,
"error": false,
"keyword": "Web scraping",
"value": 35,
"date": "2025-05-11T00:00:00",
"isPartial": false
}
```
π Output Example: Trending Now
```json
{
"scrape_type": "trending_now",
"event_index": 1,
"error": false,
"ended_timestamp": null,
"geo": "US",
"is_trend_finished": false,
"keyword": "yankees vs mets",
"normalized_keyword": "yankees vs mets",
"started_timestamp": "2026-05-15T22:20:00+00:00",
"topic_names": [
"Sports"
],
"trend_keywords": [
"yankees vs mets",
"mets game today"
],
"volume": 100000,
"volume_growth_pct": 1000
}
```
***
### π¨ Pro Tips for Maximum Success
1. **Integrated Proxies**: This scraper is built natively around Apify's Residential IP pool. **Leave Proxy configuration at default** for a seamless, unblockable experience. Our engine automatically intercepts proxy rotation cycles to ensure fresh HTTP sessions, fully bypassing Google's strict 429 rate limits.
2. **Smart Backpressure**: If Google returns sudden errors, our engine applies *invisible exponential backoff*βsaving your session without double billing you for failed API calls. Permanent errors are surfaced cleanly to your dataset without crashing the Actor.
3. **Patience on "All" Data**: Pulling absolute historical footprints (2004-Present) for 5 keywords simultaneously generates massive payloads. The Actor will work reliably, just give it a minute!
*Disclaimer: This scraper leverages sophisticated data routing and is not affiliated with Google LLC. Built for structured open data intelligence.*
# Actor input Schema
## `scrape_type` (type: `string`):
What to retrieve from Google Trends.
## `keywords` (type: `array`):
Keywords to analyze (Max 5). Required for all types except 'trending\_now'. For 'related\_\*', only the first keyword is used.
## `timeframe_type` (type: `string`):
Use a predefined timeframe or a custom range.
## `predefined_timeframe` (type: `string`):
Common timeframes used by Google Trends.
## `custom_timeframe` (type: `string`):
Custom date range (e.g., '2023-01-01 2023-06-30') or hourly.
## `geo_selection_type` (type: `string`):
Choose between a common country code or a custom geo code.
## `common_geo` (type: `string`):
Two-letter country code like 'US', 'GB', 'DE'. Leave empty for global.
## `custom_geo_code` (type: `string`):
Specific geo code (e.g., 'US-CA' for California).
## `gprop` (type: `string`):
Filter by Google service.
## `geo_resolution` (type: `string`):
Controls the level of geographic detail.
## `inc_low_vol` (type: `boolean`):
Include regions with low search volume. (Warning: high event output).
## `trending_language` (type: `string`):
Language code for realtime trending (e.g., 'en', 'es').
## `trending_hours` (type: `integer`):
Time window (1-191 hours) for realtime trending.
## `max_events` (type: `integer`):
Caps the number of items yielded. Default 100 costs ~$0.25. Limit to 10 for a $0.025 test run!
## `acknowledge_costs` (type: `boolean`):
Check this box if you plan to extract >1000 items ($2.40+) in a single run.
## `debug_mode` (type: `boolean`):
Enable verbose logging and save raw HTML/responses to Apify Key-Value Store on failure.
## `proxyConfiguration` (type: `object`):
Apify Proxy (Residential) is used automatically inside the actor code. Leave default.
## Actor input object example
```json
{
"scrape_type": "trending_now",
"keywords": [
"Web scraping"
],
"timeframe_type": "predefined",
"predefined_timeframe": "today 12-m",
"geo_selection_type": "Common Countries",
"common_geo": "US",
"custom_geo_code": "",
"gprop": "web",
"geo_resolution": "COUNTRY",
"inc_low_vol": false,
"trending_language": "en",
"trending_hours": 24,
"max_events": 100,
"acknowledge_costs": false,
"debug_mode": false,
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}
```
# 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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"keywords": [
"Web scraping"
],
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
};
// Run the Actor and wait for it to finish
const run = await client.actor("scraperpro/google-trends-ppe").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 = {
"keywords": ["Web scraping"],
"proxyConfiguration": {
"useApifyProxy": True,
"apifyProxyGroups": ["RESIDENTIAL"],
},
}
# Run the Actor and wait for it to finish
run = client.actor("scraperpro/google-trends-ppe").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"
],
"proxyConfiguration": {
"useApifyProxy": true,
"apifyProxyGroups": [
"RESIDENTIAL"
]
}
}' |
apify call scraperpro/google-trends-ppe --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=scraperpro/google-trends-ppe",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Google Trends Scraper",
"description": "Extract Real-Time Trends, Historical Data, Regional Demand, and Related Queries. Native proxy rotation bypasses rate limits. Pay-per-result pricing.",
"version": "2.6",
"x-build-id": "HSaQE30bqPYE77PbN"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/scraperpro~google-trends-ppe/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-scraperpro-google-trends-ppe",
"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/scraperpro~google-trends-ppe/runs": {
"post": {
"operationId": "runs-sync-scraperpro-google-trends-ppe",
"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/scraperpro~google-trends-ppe/run-sync": {
"post": {
"operationId": "run-sync-scraperpro-google-trends-ppe",
"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": [
"scrape_type"
],
"properties": {
"scrape_type": {
"title": "Scrape Type",
"enum": [
"trending_now",
"interest_over_time",
"interest_by_region",
"related_queries",
"related_topics"
],
"type": "string",
"description": "What to retrieve from Google Trends.",
"default": "trending_now"
},
"keywords": {
"title": "Keywords",
"maxItems": 5,
"type": "array",
"description": "Keywords to analyze (Max 5). Required for all types except 'trending_now'. For 'related_*', only the first keyword is used.",
"default": [
"Web scraping"
],
"items": {
"type": "string"
}
},
"timeframe_type": {
"title": "Timeframe Type",
"enum": [
"predefined",
"custom"
],
"type": "string",
"description": "Use a predefined timeframe or a custom range.",
"default": "predefined"
},
"predefined_timeframe": {
"title": "Predefined 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": "Common timeframes used by Google Trends.",
"default": "today 12-m"
},
"custom_timeframe": {
"title": "Custom Timeframe",
"type": "string",
"description": "Custom date range (e.g., '2023-01-01 2023-06-30') or hourly."
},
"geo_selection_type": {
"title": "Geographic Selection Type",
"enum": [
"Common Countries",
"Custom Geo Code"
],
"type": "string",
"description": "Choose between a common country code or a custom geo code.",
"default": "Common Countries"
},
"common_geo": {
"title": "Common Country (2-letter code)",
"type": "string",
"description": "Two-letter country code like 'US', 'GB', 'DE'. Leave empty for global.",
"default": "US"
},
"custom_geo_code": {
"title": "Custom Geo Code",
"type": "string",
"description": "Specific geo code (e.g., 'US-CA' for California).",
"default": ""
},
"gprop": {
"title": "Search Property (gprop)",
"enum": [
"web",
"images",
"news",
"shopping",
"youtube"
],
"type": "string",
"description": "Filter by Google service.",
"default": "web"
},
"geo_resolution": {
"title": "Geographic Resolution (for interest_by_region)",
"enum": [
"COUNTRY",
"REGION",
"DMA",
"CITY"
],
"type": "string",
"description": "Controls the level of geographic detail.",
"default": "COUNTRY"
},
"inc_low_vol": {
"title": "Include Low Volume Regions",
"type": "boolean",
"description": "Include regions with low search volume. (Warning: high event output).",
"default": false
},
"trending_language": {
"title": "Trending Now: Language",
"type": "string",
"description": "Language code for realtime trending (e.g., 'en', 'es').",
"default": "en"
},
"trending_hours": {
"title": "Trending Now: Hours",
"minimum": 1,
"maximum": 191,
"type": "integer",
"description": "Time window (1-191 hours) for realtime trending.",
"default": 24
},
"max_events": {
"title": "Maximum events to output",
"minimum": 1,
"maximum": 10000,
"type": "integer",
"description": "Caps the number of items yielded. Default 100 costs ~$0.25. Limit to 10 for a $0.025 test run!",
"default": 100
},
"acknowledge_costs": {
"title": "Acknowledge High Volume Runs",
"type": "boolean",
"description": "Check this box if you plan to extract >1000 items ($2.40+) in a single run.",
"default": false
},
"debug_mode": {
"title": "Debug Mode",
"type": "boolean",
"description": "Enable verbose logging and save raw HTML/responses to Apify Key-Value Store on failure.",
"default": false
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Apify Proxy (Residential) is used automatically inside the actor code. Leave 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
}
}
}
}
}
}
}
}
}
}
```