# Google Trends Scraper (`syntellect_ai/google-trends-scraper`) Actor "Scrape Google Trends data with built-in AI trend prediction. Get interest over time, related queries, topics, and regional interest — plus forecasts, momentum indicators, pattern detection, and breakout alerts. Supports multiple search terms, custom time ranges, and geographic filtering." - **URL**: https://apify.com/syntellect\_ai/google-trends-scraper.md - **Developed by:** [christopher athans crow](https://apify.com/syntellect_ai) (community) - **Categories:** AI, Automation, SEO tools - **Stats:** 68 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $14.99/month + usage To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period.You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#rental-actors ## 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 Scrape Google Trends data including interest over time, related queries, related topics, and regional interest. Built for the Apify platform. ### Features - 🔍 **Multiple search terms** - Compare up to 5 keywords at once - 🌍 **Geographic filtering** - Filter by country/region - 📅 **Flexible time ranges** - From past hour to past 5 years - 📊 **Comprehensive data extraction**: - Interest over time (time series) - Related queries (top & rising) - Related topics (top & rising) - Interest by region/subregion - 🔄 **Automatic retries** - Handles rate limiting gracefully - 🛡️ **Proxy support** - Residential proxies for reliability ### Input | Field | Type | Description | Default | |-------|------|-------------|---------| | `searchTerms` | array | Keywords to search (required) | - | | `geo` | string | Country code (e.g., "US", "GB") | "" (worldwide) | | `timeRange` | string | Time period for data | "today 12-m" | | `category` | number | Google Trends category ID | 0 (all) | | `proxyConfiguration` | object | Apify proxy settings | Residential | | `maxConcurrency` | number | Parallel requests (1-5) | 1 | #### Time Range Options - `now 1-H` - Past hour - `now 4-H` - Past 4 hours - `now 1-d` - Past day - `now 7-d` - Past 7 days - `today 1-m` - Past 30 days - `today 3-m` - Past 90 days - `today 12-m` - Past 12 months - `today 5-y` - Past 5 years ### Output Each search term produces one dataset item: ```json { "searchTerm": "artificial intelligence", "geo": "US", "timeRange": "today 12-m", "scrapedAt": "2026-01-18T05:25:00.000Z", "interestOverTime": [ { "date": "Jan 19, 2025", "value": 75 }, { "date": "Jan 26, 2025", "value": 82 } ], "relatedQueries": { "top": [{ "query": "chatgpt", "value": 100 }], "rising": [{ "query": "claude ai", "value": "+5000%" }] }, "relatedTopics": { "top": [{ "topic": "Machine learning", "value": 100 }], "rising": [{ "topic": "Large language model", "value": "+2500%" }] }, "interestByRegion": [ { "region": "California", "value": 100 }, { "region": "New York", "value": 92 } ] } ```` ### Usage #### Apify Console 1. Go to the Actor page 2. Enter your search terms 3. Configure location and time range 4. Click "Start" 5. Download results as JSON, CSV, or Excel #### API ```bash curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~google-trends-scraper/runs" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "searchTerms": ["typescript", "javascript"], "geo": "US", "timeRange": "today 12-m" }' ``` #### JavaScript ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_API_TOKEN' }); const run = await client.actor('YOUR_USERNAME/google-trends-scraper').call({ searchTerms: ['react', 'vue', 'angular'], geo: 'US', timeRange: 'today 12-m', }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### Cost Optimization - Use `maxConcurrency: 1` to minimize proxy costs - Shorter time ranges return faster - Batch related keywords to reduce total runs ### Limitations - Maximum 5 search terms per run - Google may rate-limit aggressive scraping - Some data may not be available for low-volume terms ### Claude Desktop MCP Server This scraper exposes a Model Context Protocol (MCP) server that provides Google Trends tools directly to Claude Desktop. #### Features - **Real Browser Fetching**: Uses Playwright to bypass Google's anti-bot measures - **Rotating Proxies**: Support for rotating residential proxies - **13 Tools**: Full suite of data fetching and analysis tools - **Analysis**: Built-in momentum calculation, pattern detection, and hypothesis generation #### Tools Included 1. **Data Fetching**: `get_interest_over_time`, `get_trending_searches`, `get_realtime_trending`, `get_related_queries`, `get_related_topics`, `get_interest_by_region`, `compare_trends` 2. **Analysis**: `predict_trend`, `analyze_momentum`, `detect_patterns`, `generate_hypotheses`, `calculate_moving_averages`, `forecast_values` #### Installation 1. Build the project: ```bash npm install npm run build ``` 2. Configure Claude Desktop (Settings -> Developer -> Edit Config): ```json { "mcpServers": { "google-trends": { "command": "node", "args": ["C:/path/to/trends_scraper/dist/mcp-server.js"], "env": { "PROXY_SERVER": "http://your-proxy.com:8080", "PROXY_USERNAME": "user", "PROXY_PASSWORD": "pass", "PROXY_ROTATE": "true" } } } } ``` #### Proxy Configuration To avoid being blocked by Google, use residential proxies. You can configure them via environment variables in your MCP config: - `PROXY_SERVER`: URL of your proxy server (e.g., `http://gate.smartproxy.com:7000`) - `PROXY_USERNAME`: Proxy username - `PROXY_PASSWORD`: Proxy password - `PROXY_ROTATE`: Set to `true` to rotate IP on every request ### Support For issues or feature requests, please open an issue on the Actor's GitHub repository. # Actor input Schema ## `searchTerms` (type: `array`): List of keywords or phrases to search for on Google Trends. Enter each term on a new line. ## `geo` (type: `string`): Two-letter country code (e.g., 'US', 'GB', 'DE') or leave empty for worldwide results. ## `timeRange` (type: `string`): Time period for trend data. ## `category` (type: `integer`): Google Trends category ID. Leave as 0 for all categories. See https://github.com/pat310/google-trends-api/wiki/Google-Trends-Categories for IDs. ## `searchType` (type: `string`): Type of search to perform (Web, Image, News, YouTube, Shopping). ## `proxyConfiguration` (type: `object`): Proxy settings for avoiding rate limits. Residential proxies are REQUIRED for best results. ## `maxConcurrency` (type: `integer`): Maximum number of pages to scrape in parallel. Lower values reduce chance of being blocked. ## `sessionPoolSize` (type: `integer`): Number of browser sessions to maintain in the rotation pool. Higher values provide more IP rotation but use more memory. ## `minDelayBetweenRequests` (type: `integer`): Minimum wait time between requests in milliseconds. Higher values help avoid rate limiting. ## `maxDelayBetweenRequests` (type: `integer`): Maximum wait time between requests in milliseconds. The actual delay is randomized between min and max. ## `enablePrediction` (type: `boolean`): Generate AI-powered trend predictions including forecasts, momentum indicators, pattern detection, and breakout alerts. ## `forecastDays` (type: `integer`): Number of days to forecast into the future (1-30 days). ## `includeCityData` (type: `boolean`): Fetch interest broken down by city in addition to state/region. ## `kvFlushIntervalMs` (type: `integer`): Interval in milliseconds to periodically flush metrics to Key-Value store. Set to 0 to disable periodic flush. ## Actor input object example ```json { "searchTerms": [ "typescript" ], "geo": "US", "timeRange": "today 12-m", "category": 0, "searchType": "", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "countryCode": "US" }, "maxConcurrency": 1, "sessionPoolSize": 10, "minDelayBetweenRequests": 3000, "maxDelayBetweenRequests": 8000, "enablePrediction": true, "forecastDays": 7, "includeCityData": false, "kvFlushIntervalMs": 30000 } ``` # 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": [ "typescript" ], "geo": "US", "timeRange": "today 12-m", "category": 0, "searchType": "", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "countryCode": "US" }, "maxConcurrency": 1, "sessionPoolSize": 10, "minDelayBetweenRequests": 3000, "maxDelayBetweenRequests": 8000, "enablePrediction": true, "forecastDays": 7, "includeCityData": false, "kvFlushIntervalMs": 30000 }; // Run the Actor and wait for it to finish const run = await client.actor("syntellect_ai/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": ["typescript"], "geo": "US", "timeRange": "today 12-m", "category": 0, "searchType": "", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], "countryCode": "US", }, "maxConcurrency": 1, "sessionPoolSize": 10, "minDelayBetweenRequests": 3000, "maxDelayBetweenRequests": 8000, "enablePrediction": True, "forecastDays": 7, "includeCityData": False, "kvFlushIntervalMs": 30000, } # Run the Actor and wait for it to finish run = client.actor("syntellect_ai/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": [ "typescript" ], "geo": "US", "timeRange": "today 12-m", "category": 0, "searchType": "", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "countryCode": "US" }, "maxConcurrency": 1, "sessionPoolSize": 10, "minDelayBetweenRequests": 3000, "maxDelayBetweenRequests": 8000, "enablePrediction": true, "forecastDays": 7, "includeCityData": false, "kvFlushIntervalMs": 30000 }' | apify call syntellect_ai/google-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=syntellect_ai/google-trends-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Trends Scraper", "description": "\"Scrape Google Trends data with built-in AI trend prediction. Get interest over time, related queries, topics, and regional interest — plus forecasts, momentum indicators, pattern detection, and breakout alerts. Supports multiple search terms, custom time ranges, and geographic filtering.\"", "version": "1.0", "x-build-id": "6EzuX0K3sOdT1gcU3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/syntellect_ai~google-trends-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-syntellect_ai-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/syntellect_ai~google-trends-scraper/runs": { "post": { "operationId": "runs-sync-syntellect_ai-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/syntellect_ai~google-trends-scraper/run-sync": { "post": { "operationId": "run-sync-syntellect_ai-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", "required": [ "searchTerms" ], "properties": { "searchTerms": { "title": "Search Terms", "type": "array", "description": "List of keywords or phrases to search for on Google Trends. Enter each term on a new line.", "items": { "type": "string" }, "default": [ "typescript" ] }, "geo": { "title": "Geographic Location", "type": "string", "description": "Two-letter country code (e.g., 'US', 'GB', 'DE') or leave empty for worldwide results.", "default": "US" }, "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" ], "type": "string", "description": "Time period for trend data.", "default": "today 12-m" }, "category": { "title": "Category", "minimum": 0, "type": "integer", "description": "Google Trends category ID. Leave as 0 for all categories. See https://github.com/pat310/google-trends-api/wiki/Google-Trends-Categories for IDs.", "default": 0 }, "searchType": { "title": "Search Type", "enum": [ "", "images", "news", "youtube", "froogle" ], "type": "string", "description": "Type of search to perform (Web, Image, News, YouTube, Shopping).", "default": "" }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings for avoiding rate limits. Residential proxies are REQUIRED for best results." }, "maxConcurrency": { "title": "Max Concurrency", "minimum": 1, "maximum": 5, "type": "integer", "description": "Maximum number of pages to scrape in parallel. Lower values reduce chance of being blocked.", "default": 1 }, "sessionPoolSize": { "title": "Session Pool Size", "minimum": 1, "maximum": 50, "type": "integer", "description": "Number of browser sessions to maintain in the rotation pool. Higher values provide more IP rotation but use more memory.", "default": 10 }, "minDelayBetweenRequests": { "title": "Minimum Delay Between Requests (ms)", "minimum": 1000, "maximum": 30000, "type": "integer", "description": "Minimum wait time between requests in milliseconds. Higher values help avoid rate limiting.", "default": 3000 }, "maxDelayBetweenRequests": { "title": "Maximum Delay Between Requests (ms)", "minimum": 2000, "maximum": 60000, "type": "integer", "description": "Maximum wait time between requests in milliseconds. The actual delay is randomized between min and max.", "default": 8000 }, "enablePrediction": { "title": "Enable Trend Prediction", "type": "boolean", "description": "Generate AI-powered trend predictions including forecasts, momentum indicators, pattern detection, and breakout alerts.", "default": true }, "forecastDays": { "title": "Forecast Days", "minimum": 1, "maximum": 30, "type": "integer", "description": "Number of days to forecast into the future (1-30 days).", "default": 7 }, "includeCityData": { "title": "Include City Data", "type": "boolean", "description": "Fetch interest broken down by city in addition to state/region.", "default": false }, "kvFlushIntervalMs": { "title": "KV Flush Interval (ms)", "minimum": 0, "maximum": 86400000, "type": "integer", "description": "Interval in milliseconds to periodically flush metrics to Key-Value store. Set to 0 to disable periodic flush.", "default": 30000 } } }, "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 } } } } } } } } } } ```