# Google Trends Scraper API (`cleanscrape/google-trends-scraper`) Actor Scrape Google Trends reliably — interest over time, related & rising queries, interest by region, and trending searches. Clean normalized JSON/CSV output. - **URL**: https://apify.com/cleanscrape/google-trends-scraper.md - **Developed by:** [CleanScrape](https://apify.com/cleanscrape) (community) - **Categories:** SEO tools, Developer tools, E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 API Reliable Google Trends data in one normalized dataset — every surface Google Trends exposes: - **Interest over time** — search-interest values (0–100) per keyword, over your chosen timeframe and geo. - **Related & rising queries** — the top and breakout queries associated with each keyword. - **Related topics** — the top and rising topics (entities) associated with each keyword. - **Interest by region** — which countries / regions / cities / metros search most for each keyword. - **Trending now** — the currently trending searches for a country, with approximate traffic and related news. Built for reliability. Google Trends has no official public API and aggressively rate-limits its internal endpoints — which is why many scrapers fail intermittently. This actor routes through **residential proxy**, bootstraps Google's consent cookie before every session, and retries with exponential backoff, so runs complete instead of silently returning nothing. ### Why this one - **One normalized schema** for all three data types (discriminated by a `dataType` field) — load it straight into a spreadsheet or pipeline. - **Residential-proxy routed + retry-hardened** against the 429 rate limits that break naive scrapers. - **No login, no personal data** — public aggregate trend data only. ### Input | Field | Description | |-------|-------------| | `searchTerms` | Up to 5 keywords (Google compares max 5). Required for all data types except `trending_now`. | | `dataTypes` | Any of `interest_over_time`, `related_queries`, `related_topics`, `interest_by_region`, `trending_now`. | | `regionResolution` | For `interest_by_region`: `COUNTRY`, `REGION`, `CITY`, or `DMA`. | | `geo` | Two-letter country code (e.g. `US`, `GB`, `FI`); empty = worldwide. | | `timeframe` | e.g. `today 12-m`, `today 5-y`, `now 7-d`, or `YYYY-MM-DD YYYY-MM-DD`. | | `category` | Google Trends category ID (0 = all). | | `language` | Interface language, e.g. `en-US`, `fi-FI`. | | `trendingGeo` | Country for the trending-now feed. | | `proxyConfiguration` | Proxy routing. **Residential Apify Proxy is strongly recommended** — Google rate-limits datacenter IPs hard. | #### How to find IDs - **Timeframe** and **category** mirror the options on trends.google.com. - **Geo** is the standard ISO two-letter country code. ### Example output Interest over time: ```json { "dataType": "interest_over_time", "keyword": "bitcoin", "geo": "US", "timeframe": "today 12-m", "date": "Jul 8 2026", "value": 72, "isPartial": false } ```` Trending now: ```json { "dataType": "trending_now", "geo": "US", "rank": 1, "query": "example topic", "approxTraffic": "50000+", "relatedNews": ["Headline one", "Headline two"] } ``` ### Reliability by data type Google defends its Trends endpoints unevenly, so this actor is honest about it: - **Interest over time** and **Trending now** are **reliable** — these are the default, and they complete consistently (interest-over-time via residential-IP rotation, trending via Google's stable RSS feed). - **Related queries**, **related topics**, and **interest by region** are **best-effort**. They use Google's most heavily rate-limited endpoints; the actor rotates through a pool of residential IPs and retries, but under load Google may still block them, in which case that data type returns nothing (the run still succeeds and you're only charged for rows delivered). For best results, request these one at a time. ### Notes & limits - **Residential proxy is important.** Google rate-limits these endpoints heavily on datacenter/unproxied IPs; the actor routes through a pool of residential IPs and rotates to a fresh IP on every retry, which is what keeps the reliable data types completing. - **`trending_now`** uses Google's trending RSS feed — the most stable Trends surface — and needs no keywords. - Google Trends values are **relative** (0–100, scaled to the peak within your query), not absolute search counts — this is how Google Trends works, not a limitation of the scraper. ### Common uses - Track demand/seasonality for products, tickers, or topics. - Find breakout ("rising") queries for content and SEO. - Monitor what's trending in a country for newsroom/marketing workflows. # Actor input Schema ## `searchTerms` (type: `array`): Up to 5 keywords to analyze (Google Trends compares max 5). Required for interest-over-time and related queries. ## `dataTypes` (type: `array`): Which datasets to fetch. ## `regionResolution` (type: `string`): Granularity for 'Interest by region'. ## `geo` (type: `string`): Two-letter country code to scope results (e.g. US, GB, FI). Leave empty for worldwide. ## `timeframe` (type: `string`): Google Trends time range, e.g. 'today 12-m', 'today 5-y', 'now 7-d', 'now 1-H', or 'YYYY-MM-DD YYYY-MM-DD'. ## `category` (type: `integer`): Google Trends category ID to narrow results (0 = all categories). ## `language` (type: `string`): Interface language code, e.g. en-US, fi-FI. ## `trendingGeo` (type: `string`): Country code for the 'Trending now' feed (defaults to Geo, or US). ## `proxyConfiguration` (type: `object`): Proxy routing. Residential Apify Proxy is strongly recommended for reliability against Google rate limits. ## Actor input object example ```json { "searchTerms": [ "bitcoin", "ethereum" ], "dataTypes": [ "interest_over_time", "trending_now" ], "regionResolution": "COUNTRY", "geo": "", "timeframe": "today 12-m", "category": 0, "language": "en-US", "trendingGeo": "US", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `results` (type: `string`): All fetched Google Trends rows as 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchTerms": [ "bitcoin", "ethereum" ] }; // Run the Actor and wait for it to finish const run = await client.actor("cleanscrape/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": [ "bitcoin", "ethereum", ] } # Run the Actor and wait for it to finish run = client.actor("cleanscrape/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": [ "bitcoin", "ethereum" ] }' | apify call cleanscrape/google-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=cleanscrape/google-trends-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Trends Scraper API", "description": "Scrape Google Trends reliably — interest over time, related & rising queries, interest by region, and trending searches. Clean normalized JSON/CSV output.", "version": "0.1", "x-build-id": "6mLBp09UXzPLJk2bf" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cleanscrape~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cleanscrape-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/cleanscrape~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-cleanscrape-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/cleanscrape~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-cleanscrape-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", "type": "array", "description": "Up to 5 keywords to analyze (Google Trends compares max 5). Required for interest-over-time and related queries.", "items": { "type": "string" } }, "dataTypes": { "title": "Data types", "type": "array", "description": "Which datasets to fetch.", "items": { "type": "string", "enum": [ "interest_over_time", "related_queries", "related_topics", "interest_by_region", "trending_now" ], "enumTitles": [ "Interest over time (reliable)", "Related & rising queries (best-effort)", "Related topics (best-effort)", "Interest by region (best-effort)", "Trending now (reliable)" ] }, "default": [ "interest_over_time", "trending_now" ] }, "regionResolution": { "title": "Region resolution", "enum": [ "COUNTRY", "REGION", "CITY", "DMA" ], "type": "string", "description": "Granularity for 'Interest by region'.", "default": "COUNTRY" }, "geo": { "title": "Geo (country code)", "type": "string", "description": "Two-letter country code to scope results (e.g. US, GB, FI). Leave empty for worldwide.", "default": "" }, "timeframe": { "title": "Timeframe", "type": "string", "description": "Google Trends time range, e.g. 'today 12-m', 'today 5-y', 'now 7-d', 'now 1-H', or 'YYYY-MM-DD YYYY-MM-DD'.", "default": "today 12-m" }, "category": { "title": "Category ID", "type": "integer", "description": "Google Trends category ID to narrow results (0 = all categories).", "default": 0 }, "language": { "title": "Language (hl)", "type": "string", "description": "Interface language code, e.g. en-US, fi-FI.", "default": "en-US" }, "trendingGeo": { "title": "Trending-now country", "type": "string", "description": "Country code for the 'Trending now' feed (defaults to Geo, or US).", "default": "US" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Proxy routing. Residential Apify Proxy is strongly recommended for reliability against Google rate limits.", "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 } } } } } } } } } } ```