# Google Trends Scraper API: Real-Time & Historical Search Trends (`unitbytes/google-trends-scraper-api`) Actor Extract real-time Google search trends, historical keyword interest, regional demand, and related queries without rate limits. Fast, proxy-rotated, and pay per event. - **URL**: https://apify.com/unitbytes/google-trends-scraper-api.md - **Developed by:** [UnitBytes | Enterprise Web Data](https://apify.com/unitbytes) (community) - **Categories:** SEO tools, Marketing, E-commerce - **Stats:** 15 total users, 7 monthly users, 78.9% runs succeeded, 1 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $1.20 / 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. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README

Google Trends Real-Time & Historical API by UnitBytes

## πŸ“Š Google Trends Fast Scraper β€” Flat Tabular & CSV Output (5 Endpoints, 99.9% Success) > **The easiest and most reliable Google Trends extractor on Apify.** Extract realtime trending searches, 2004–present historical timelines, geographic heatmaps, and breakout queries formatted as **clean, flat rows** ready for 1-click export to **Excel, CSV, Google Sheets, or databases**. No nested arrays, no custom parsing code required! *** ### πŸ† Why Choose This Scraper? Most Google Trends scrapers return deeply nested JSON structures that are difficult to work with unless you write custom scripts to flatten arrays. Furthermore, they frequently suffer from Google's strict rate limits (`429 Too Many Requests`). This scraper is built from the ground up to solve both problems: - πŸ“‹ **1-Click Clean CSV/Excel Ready**: Every single data point is saved as an unnested, flat tabular row. Simply click **"Export to CSV"** or **"Export to Excel"** in the Apify Console and your dataset is instantly ready for analysis. - ⚑ **All 5 Endpoints in 1 Actor**: Retrieve *Trending Now*, *Interest Over Time*, *Interest by Region*, *Related Queries*, and *Related Topics* without paying for multiple actors. - πŸ›‘οΈ **Automated Anti-Blocking & Smart IP Rotation**: Automated Apify residential proxy rotation cycles IPs and handles Google's rate limits behind the scenes. - πŸ’° **Transparent Pay-Per-Result (PPE)**: You only pay for successfully extracted rows. Check the **Pricing** tab for current rates. No recurring monthly rentals, zero proxy fees, and zero compute runtime fees. - πŸ”„ **Multi-Keyword Support**: Compare up to 5 keywords simultaneously or loop through keyword lists automatically up to your specified limit. - πŸ€– **AI Agent & No-Code Ready**: Natively compatible with the Apify MCP Server (Cursor, Claude Desktop), Make, N8N, and Google Sheets. *** ### πŸ“‘ 5 Core Intelligence Endpoints Select your desired mode using the `scrape_type` parameter: #### 1. πŸš€ `trending_now` β€” Real-Time Search Pulses Discover what the world is searching for *right now*. Monitor viral breakout spikes hourly with estimated search volumes, percentage growth, category tags, and context-rich news articles. **Flat CSV / JSON Row Preview:** ```json { "scrape_type": "trending_now", "keyword": "Champions League Final", "volume": 250000, "volume_growth_pct": 850, "topic_names": ["Sports", "Soccer"], "article_title": "Match Preview and Lineups Announced", "article_source": "BBC Sport", "article_url": "https://www.bbc.com/sport/football/...", "started_timestamp": "2026-06-01T18:00:00+00:00" } ``` *** #### 2. πŸ“ˆ `interest_over_time` β€” Historical Timeline (2004 – Present) Track relative search popularity on a normalized 0–100 scale across any timeframeβ€”from the past hour to over 20 years of historical data. Compare up to 5 keywords on the exact same scale. **Flat CSV / JSON Row Preview:** ```json { "scrape_type": "interest_over_time", "keyword": "Artificial Intelligence", "date": "2025-01-01T00:00:00+00:00", "value": 84, "isPartial": false } ``` *** #### 3. πŸ—ΊοΈ `interest_by_region` β€” Geographic Demand Breakdown Pinpoint exactly where consumer demand is centralized. Filter by **Country**, **Region (State/Province)**, **Metro DMA**, or **City**. **Flat CSV / JSON Row Preview:** ```json { "scrape_type": "interest_by_region", "keyword": "Electric Vehicles", "geo_code": "US-CA", "geo_name": "California", "value": 100, "max_value_index": 0 } ``` *** #### 4. πŸ” `related_queries` β€” Long-Tail & Breakout Queries Unearth the exact search queries people enter alongside your target keywords. Automatically separates established **"Top"** queries from explosive **"Rising"** breakout queries (up to `+5000%` growth). **Flat CSV / JSON Row Preview:** ```json { "scrape_type": "related_queries", "keyword": "SaaS Marketing", "query_type": "rising", "query": "ai marketing automation tools", "value": 450, "formatted_value": "+450%" } ``` *** #### 5. 🏷️ `related_topics` β€” Knowledge Graph Entity Extraction Extract Google's contextual entity groupings. Understand how Google's search algorithms categorize your market or brand. **Flat CSV / JSON Row Preview:** ```json { "scrape_type": "related_topics", "keyword": "Notion", "topic_type": "top", "topic_title": "Productivity software", "topic_type_label": "Software", "value": 100 } ``` *** ### ⏱️ Timeframe vs. Data Granularity Guide Google Trends automatically adjusts data point frequency based on your chosen timeframe. Use this cheat sheet to choose the right setting: | Timeframe Option | Granularity Returned | Ideal Use Case | | :--- | :--- | :--- | | `now 1-H`, `now 4-H` | **Minute-by-minute** | Breaking news, viral spikes, live sports events | | `now 1-d`, `now 7-d` | **Hourly intervals** | Weekly campaign tracking, product launch momentum | | `today 1-m`, `today 3-m` | **Daily data points** | Monthly performance audits, seasonal trend tracking | | `today 12-m`, `today 5-y` | **Weekly data points** | Multi-year demand forecasting, competitor benchmarking | | `all` (2004 – Present) | **Monthly data points** | Macro industry evolution, historical retrospective analysis | *** ### πŸ’Ž Transparent Pay-Per-Event Pricing Stop paying high recurring monthly subscriptions or paying for idle compute time. This actor operates on Apify's **Pay-Per-Event (PPE)** model: | Benefit | Details | | :--- | :--- | | **Pay-Per-Result** | You only pay for successfully extracted results. Check the **Pricing** tab above for the current live rate. | | **Residential Proxies Included** | Built-in smart residential proxy rotation is included at no additional charge. | | **No Compute Time Fees** | You never pay for startup time, queueing, or scrape runtime delays. | | **Zero-Risk Guarantee** | Failed requests or empty queries are never charged. | *** ### 🎯 Use Cases #### πŸ“¦ E-Commerce & Dropshipping Identify breakout products *before* they saturate the market. Run `trending_now` daily across multiple countries and cross-reference with `interest_over_time` to separate viral fads from sustained commercial demand. Catch consumer product waves on TikTok and Instagram weeks before they peak on Amazon. #### ✍️ SEO & Content Marketing Use `related_queries` to discover explosive long-tail queries with rising search volume (+5000% breakout) that competitors haven't targeted yet. Use `interest_over_time` to time content publishing to peak seasonal demand. #### πŸ’Έ Quantitative Finance & Trading Correlate `interest_over_time` spikes for ticker symbols, crypto, commodities, or brand names with market volatility. Search volume trends often predict retail trading volume and momentum shifts. #### πŸ“Š Market Research & Brand Intelligence Track brand awareness over time against rivals using `interest_over_time` with up to 5 keywords simultaneously. Use `interest_by_region` to find underserved geographic markets and plan localized expansion campaigns. *** ### πŸ€– AI & Workflow Automations Because results are saved as clean flat rows, you can plug this actor directly into your automation pipelines: - πŸ“Š **Google Sheets & Airtable**: Automatically append new trending rows to your spreadsheets without needing formatting scripts. - πŸ”„ **Make (Integromat) & N8N**: Trigger alerts or content generation workflows when keyword search volume crosses thresholds. - πŸ€– **Model Context Protocol (MCP)**: Connect this scraper directly to **Cursor, Claude Desktop, or custom AI Agents** via the Apify MCP server to give your LLM live Google Trends research capabilities. - 🐍 **LangChain & LlamaIndex**: Load tabular search trends into your RAG pipelines and research agents. *** ### πŸ’» Quick Start Code Examples #### Python ```python from apify_client import ApifyClient client = ApifyClient("YOUR_APIFY_TOKEN") ## Run Google Trends Fast Scraper run = client.actor("unitbytes/google-trends-ppe\").call(run_input={ "scrape_type": "interest_over_time", "keywords": ["OpenAI", "Anthropic", "DeepSeek"], "timeframe_type": "predefined", "predefined_timeframe": "today 12-m", "common_geo": "US", "max_events": 500 }) ## Iterate directly through flat rows for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(f"[{item['date']}] {item['keyword']}: {item['value']}") ``` #### Node.js (JavaScript / TypeScript) ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' }); const run = await client.actor("unitbytes/google-trends-ppe\").call({ scrape_type: 'related_queries', keywords: ['AI Tools'], timeframe_type: 'predefined', predefined_timeframe: 'today 3-m', common_geo: 'US', max_events: 50 }); // Fetch flat rows const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach(row => { console.log(`${row.query_type.toUpperCase()}: ${row.query} (${row.formatted_value})`); }); ``` *** ### βš™οΈ Input Parameters | Parameter | Type | Required | Default | Description | | :--- | :--- | :--- | :--- | :--- | | `scrape_type` | string | **Yes** | `trending_now` | One of: `trending_now`, `interest_over_time`, `interest_by_region`, `related_queries`, `related_topics` | | `keywords` | array | Cond. | `[]` | List of 1 to 5 keywords (required for all types except `trending_now`) | | `timeframe_type`| string | No | `predefined` | `predefined` or `custom` | | `predefined_timeframe` | string | No | `today 12-m` | Predefined window (e.g., `now 7-d`, `today 3-m`, `today 12-m`, `all`) | | `custom_timeframe` | string | No | `""` | Exact date range in `YYYY-MM-DD YYYY-MM-DD` format | | `common_geo` | string | No | `""` | 2-letter country code (e.g., `US`, `GB`, `DE`). Leave blank for Worldwide | | `geo_resolution` | string | No | `REGION` | For `interest_by_region`: `COUNTRY`, `REGION`, `CITY`, or `DMA` | | `gprop` | string | No | `""` | Search property: `""` (Web), `images`, `news`, `froogle` (Shopping), `youtube` | | `max_events` | integer | No | `100` | Maximum number of data rows to extract | *** ### πŸ’‘ Pro Tips for Best Results 1. **Instant CSV Download**: In the Apify Console, click **Export** $\rightarrow$ **CSV** to download your dataset. Because this actor uses flat rows, it opens seamlessly in Microsoft Excel, Apple Numbers, and Google Sheets without any column splitting. 2. **Leave Proxies on Default**: The scraper automatically assigns Apify Residential Proxies and cycles session IPs. You do not need to configure custom proxies. 3. **Worldwide vs. Country-Specific**: For worldwide data, leave `common_geo` blank. Regional breakdown (`interest_by_region`) is most detailed when a specific country (e.g. `US`, `GB`, `DE`) is chosen. 4. **Discovering Hidden Breakouts**: Check the `rising` section of `related_queries`β€”queries marked with high percentages or "Breakout" represent emerging search trends with low SEO competition. 5. **Need Single-Envelope Nested JSON?**: If your backend API integration specifically requires all data points wrapped inside a single nested JSON object (`{"data": [...]}`), check out our companion actor: [**Google Trends Scraper (Nested Batch API)**](https://apify.com/unitbytes/google-trends-scraper). *** ### ❓ Frequently Asked Questions **Q: Why use this actor instead of scrapers that output nested JSON?**\ A: Most scrapers return all data nested inside single records or complex arrays. This actor formats every observation as a flat tabular row, making it ideal for immediate CSV export, spreadsheet analysis, and no-code automations without writing parsing code. **Q: Do I need to buy or configure my own proxies?**\ A: No. High-speed residential proxies are integrated directly into the scraping engine at zero extra charge. **Q: What happens if Google returns a 429 rate-limit error?**\ A: The scraper handles rate limits automatically. It detects blocks, automatically switches proxy sessions, and seamlessly resumes extraction so your scraping jobs finish reliably without manual intervention. **Q: Is scraping Google Trends legal?**\ A: Yes. This actor extracts publicly available search statistics published by Google Trends. It does not access private account information. **Q: Can I export data to Excel or CSV?**\ A: Yes. In the Apify Console, click "Export" on your dataset to download cleanly formatted Excel, CSV, JSON, or XML files. **Q: How does billing work?**\ A: You are billed strictly per successful result extracted via Apify's Pay-Per-Event model (see the **Pricing** tab for current rates). You are never charged for actor runtime, proxy bandwidth, or failed requests. *** *Keywords: Google Trends API, Google Trends scraper, Google Trends CSV export, Google Trends Excel, flat Google Trends data, interest over time scraper, related queries extractor, Google Trends keyword research, SEO trend analysis, trending searches API, regional interest data, Apify Google Trends.* *** ### πŸ’¬ Enterprise Support & Custom Pipelines Need custom web data feeds, high-frequency scheduled runs, private cluster deployments, or dedicated SLAs? - πŸ“§ **Direct Email**: - 🌐 **Enterprise Platform**: - πŸ’‘ **Data Engine Specs & Live Docs**: # 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'. ## `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("unitbytes/google-trends-scraper-api").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("unitbytes/google-trends-scraper-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"πŸ’Ύ Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).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 unitbytes/google-trends-scraper-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,unitbytes/google-trends-scraper-api" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/tg7YFhLVLZIua8gyH/builds/8sybONBnyGCSw9d4F/openapi.json