# Google Trends Scraper — Interest, Regions & Rising Queries (`cleancut/google-trends-scraper`) Actor Google Trends for many keywords and countries at once: interest over time, by region and city, top and rising related queries, trend metrics (peak, change, direction), comparisons and Trending now. All data in one row. Pay per keyword × location; errors are free. - **URL**: https://apify.com/cleancut/google-trends-scraper.md - **Developed by:** [Cleancut Data](https://apify.com/cleancut) (community) - **Categories:** SEO tools, AI - **Security:** Limited permissions - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.04 / 1,000 search term analyzed (term × location)s 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 Scraper — Interest, Regions & Rising Queries Get **Google Trends data for many keywords and countries in one run**: **interest over time**, **interest by region and by city**, **top and rising related queries** (with breakouts) and ready-made **trend metrics** — average, peak, latest value, recent and year-over-year change and a rising / stable / falling direction. Compare up to 5 terms on one scale, or list **what is trending now** in any country. **You only pay per search term × location — and everything above comes in that one row.** Terms without enough data, invalid inputs and blocked requests are reported for free. ### What can it do? - 📈 **Interest over time** — every point of the chart (minutes, hours, days, weeks or months, depending on the period), with dates in UTC and the partial-point flag. - 🧮 **Trend metrics, free** — `averageInterest`, `peakInterest` and `peakDate`, `latestInterest`, `recentChangePercent` (last month vs. the month before, partial points excluded), `yearOverYearChangePercent` for 5-year and all-time ranges, and `trendDirection`. No spreadsheet work. - 🗺️ **Interest by region and by city, free** — countries (worldwide), states or provinces (a country) or metros (a US state), plus **cities with coordinates** for maps. - 🔍 **Related queries, top and rising, free** — rank, value, `isBreakout` and a Google Trends link for each one, plus `topRelatedQuery`, `topRisingQuery` and the list of `breakoutQueries` in the overview. - ⚖️ **Comparison mode** — up to 5 terms on one shared scale (bigger lists are split in groups): each term's **share of interest**, its **share in every region** and the **number of regions where it leads**. - 🔥 **Trending now** — what people are searching right now in any country (past 4 h, 24 h, 48 h or 7 days): search volume (`20K+`), % increase, start time, active or ended, categories and the searches behind each trend. Filter by category. - 🌍 **Many terms × many locations in one run** — `["coffee", "matcha"]` × `["US", "GB", "AR"]` = 6 rows. Any time range (past hour to 2004–present, or a custom range), category, and **web, image, news, Google Shopping or YouTube search**. - 🔗 **Paste Google Trends links** — the terms, location, dates, category and search type of the link are used as they are. - ⚡ **Fast & lightweight** — plain HTTP to Google Trends' own chart data, no browser: a term with all its data in about a second. ### Who is it for? - ✍️ **SEO & content teams** — pick topics with rising demand and find breakout queries before competitors. - 🛒 **E-commerce & product research** — check seasonality, the peak month and where a product is searched the most. - 📊 **Analysts & market researchers** — compare brands or categories on one scale, by region, for years. - 📰 **Newsrooms & social teams** — monitor what is trending now in each country, every hour. - 🤖 **AI agents & automations** — call it from the [Apify MCP server](https://mcp.apify.com), n8n, Make or Zapier; every field is documented for the model. ### Input example ```json { "searchTerms": ["coffee", "matcha"], "geos": ["US", "GB"], "timeRange": "today 12-m", "mode": "terms", "include": ["timeline", "regions", "cities", "relatedQueries"] } ``` Trending now in two countries: ```json { "mode": "trending", "trendingGeos": ["US", "AR"], "trendingHours": "24" } ``` Names used by other Google Trends Actors also work (`keyword`, `isMultiple`, `geo`, `predefinedTimeframe`, `trendingSearchesCountry`…), so an existing integration keeps running. ### Output example One row per term × location (arrays shortened; real output, 4 Nov 2026): ```json { "status": "ok", "type": "interest", "searchTerm": "coffee", "geo": "US", "timeRange": "today 12-m", "timeframe": "2025-11-04 2026-11-04", "resolution": "WEEK", "dataPoints": 53, "averageInterest": 78.3, "peakInterest": 100, "peakDate": "2026-04-12T00:00:00.000Z", "latestInterest": 63, "latestIsPartial": true, "recentChangePercent": -6.1, "trendDirection": "stable", "timeline": [{ "date": "2025-11-02T00:00:00.000Z", "label": "Nov 2 – 8, 2025", "value": 67, "isPartial": false }], "regionLevel": "subregion", "interestByRegion": [{ "geoCode": "US-WY", "name": "Wyoming", "value": 100 }], "topRegion": "Wyoming", "interestByCity": [{ "name": "Pasadena", "value": 100, "lat": 34.1477849, "lng": -118.1445155 }], "relatedQueries": [ { "kind": "top", "rank": 1, "query": "coffee near me", "value": 100, "formattedValue": "100", "isBreakout": false }, { "kind": "rising", "rank": 10, "query": "how to brew pour over coffee", "value": 3200, "formattedValue": "+3,200%", "isBreakout": false } ], "topRelatedQuery": "coffee near me", "relatedQueriesCount": 50, "missingData": [], "trendsUrl": "https://trends.google.com/trends/explore?date=today%2012-m&geo=US&q=coffee&hl=en-US" } ``` A "Trending now" row: ```json { "status": "ok", "type": "trending", "rank": 1, "term": "2026 us election results", "geo": "US", "searchVolume": 10000000, "searchVolumeFormatted": "10M+", "increasePercent": 1000, "startedAt": "2026-11-03T23:00:00.000Z", "isActive": true, "categories": ["Politics"], "trendBreakdown": ["2026 us election results", "2026 united states senate elections", "house election results"] } ``` A `SUMMARY` record in the key-value store counts results, errors by code, requests and retries. #### Output views | View | What you see | |---|---| | **Trend overview** | One row per term × location: average, latest, recent and YoY change, direction, peak, top region and city, top and rising query | | **Interest over time** | One row per term and chart point, ready for a line chart | | **Interest by region** | One row per term and country, state or metro | | **Interest by city** | One row per term and city, with latitude and longitude | | **Related queries (top & rising)** | One row per related query with its value, breakout flag and link | | **Comparison** | Share of interest and regions where each compared term leads | | **Trending now** | Trending searches per country with volume, growth and breakdown | | **Errors (free)** | Why a term, link or country could not be analyzed | ### Errors (free) Error rows are never charged and always come **after** the results. | `errorCode` | Meaning | |---|---| | `NOT_ENOUGH_DATA` | Google Trends has too little search volume for this term, location and period ("not enough data" on the website) | | `BLOCKED` | Google limited the connection (captcha page). It is not retried; try again later or with fewer terms per run | | `RATE_LIMITED` | Google kept answering "too many requests" after the retries | | `INVALID_REQUEST` | Google rejected the search (check the time range, location and category) | | `INVALID_URL` | A pasted link has an unknown location or date range | | `NO_TRENDS` | "Trending now" has no trends for that country, window or category filter | | `SOURCE_ERROR` / `REQUEST_FAILED` | Google Trends or the network failed after the retries | If one secondary chart (for example cities) fails after the retries, the row is still delivered and lists it in `missingData`. ### Pricing Pay per event — **you pay per search term × location with all its data included** (timeline, regions, cities, related queries and metrics), and per trending search in "Trending now" mode. Errors are free. | Your Apify plan | Per 1,000 search terms × location | Per 1,000 trending searches | |---|---:|---:| | Every plan (Free, Starter, Scale, Business…) | **$0.04** | **$0.015** | Plus a start fee of $0.0005 per run. Example: **50 keywords in 3 countries every week** (150 rows) costs about **$0.0065 per run, $0.03 a month**; the **1,000 searches trending in the US today** cost about **$0.016**. In our side-by-side test with the same 4 keywords (4 Nov 2026), other Google Trends Actors cost $0.027–0.03 per keyword (one keyword per run with a $0.025 start fee, or a browser run billed with platform usage) or $0.005 per data point; this Actor cost $0.0005 for all 4. Set **"Max results"** or the run's maximum cost to cap spending. ### Tips - Values are **relative**: 100 is the peak of each term in that place and period. To compare two terms fairly, use **comparison mode** (one shared scale). - For **seasonality and year-over-year growth**, use "Past 5 years" or "2004 – present". - For **US metros**, use a state as the location (`US-CA`) — the region breakdown becomes metros. - **Hourly and minute data** ("Past hour" to "Past 7 days") changes quickly: schedule the run as often as you need. - Google Trends limits fast clients. The default of 6 parallel searches is fast and stable; if the summary shows many `RATE_LIMITED` retries or `BLOCKED` rows, lower it or split the run, and try again later. ### Responsible scraping The Actor only reads the chart data that the Google Trends website loads (`/trends/api/explore`, `/trends/api/widgetdata` and the "Trending now" data), which robots.txt allows; it never opens the pages robots.txt disallows. Captchas and blocks are never bypassed: a blocked request becomes a free `BLOCKED` row and is not retried through another IP. The fallback proxy is Apify datacenter (or your own proxy URLs); residential proxy is not used, which keeps the price this low. It collects aggregated search interest, no personal data. ### FAQ **Are the numbers search volumes?** No. Google Trends gives relative interest (0–100) for the term, place and period; "Trending now" gives volume buckets (`20K+`). The Actor returns exactly what Google returns. **Why are related topics missing?** Google Trends returns an empty related-topics list to automated clients (it labels the session `USER_TYPE_SCRAPER`), so no honest scraper can deliver them without a browser pretending to be a person. Related **queries** — top and rising — are complete. **Why do some rising queries look unrelated?** They are what Google returns for that term and period (they appear the same on repeated requests); the Actor does not edit Google's data. **How many terms can I run?** No limit. Large runs take longer because Google Trends limits fast clients; about 1–2 seconds per term at the default speed. **Can I schedule it?** Yes: schedule it in Apify (daily, weekly…) or call it from the API, n8n, Make or Zapier. Every run is independent and reproducible. **Is it official?** No. It's an independent tool that reads public Google Trends data; it is not affiliated with Google. ### Changelog - **0.1 (Nov 2026)** — First release: terms × locations, comparison mode with share of interest and share by region, Trending now, cities with coordinates, related queries with breakouts, trend metrics, Google Trends links as input. ### More from Cleancut Data - 📢 **[Google Ads Transparency Scraper](https://apify.com/cleancut/google-ads-transparency-scraper)**: every Google ad a competitor runs, with ad copy, images, videos, regions and dates included in the price. - ✈️ **[Google Flights Cheapest Fares](https://apify.com/cleancut/google-flights-cheapest-fares)**: the cheapest Google Flights fare per route and date, the cheapest day of the month and price-drop alerts. - 🏨 **[Google Hotels Rate Shopper](https://apify.com/cleancut/google-hotels-price-comparator)**: what every booking site charges for your hotels and dates, with taxes, free cancellation and rate-parity gaps. - 🎬 **[YouTube Transcript Scraper](https://apify.com/cleancut/youtube-transcript-scraper)**: transcripts in bulk from videos, channels, playlists and search, with SRT/VTT, AI-ready chunks, likes and publish dates. # Actor input Schema ## `searchTerms` (type: `array`): Keywords to analyze, one per line, e.g. "coffee" or "electric cars". No limit per run. Empty = demo term "coffee". ## `geos` (type: `array`): Country codes (US, GB, AR, DE…), regions (US-CA, GB-ENG, BR-SP) or US metros (US-CA-803). Empty = worldwide. Region and city breakdowns follow the location: countries for worldwide, states for a country, metros for a US state. ## `timeRange` (type: `string`): Period of the interest-over-time chart. Google picks the point size: minutes for the last hours, days up to 90 days, weeks up to 5 years, months for all time. ## `customTimeRange` (type: `string`): Optional, replaces the time range above: "YYYY-MM-DD YYYY-MM-DD", e.g. "2024-01-01 2024-12-31". Data starts on 2004-01-01. ## `mode` (type: `string`): Terms: one row per term × location, each term on its own 0–100 scale. Compare: terms in groups of up to 5 on one shared scale, with each term's share of interest and who wins in each region. Trending now: the searches trending in each country (section "Trending now"); search terms are ignored. ## `include` (type: `array`): All included by default at no extra cost. Remove what you don't need to get smaller rows. Trend metrics (average, peak, latest value, recent and year-over-year change, direction) are always included. ## `category` (type: `string`): Narrow the search to a Google Trends category, e.g. "apple" in Food & Drink instead of the company. ## `property` (type: `string`): Which Google search to measure: web (default), images, news, Google Shopping or YouTube. ## `startUrls` (type: `array`): Paste links from Google Trends, e.g. https://trends.google.com/trends/explore?q=coffee,tea\&geo=US\&date=today%2012-m. Their terms, location, dates, category and search type are used as they are (several terms in one link = a comparison). The links are read, not opened. ## `trendingGeos` (type: `array`): 2-letter country codes, one per line (US, GB, AR, IN…). Empty = US. ## `trendingHours` (type: `string`): Time window of the trending searches. ## `trendingCategories` (type: `array`): Only trends in these categories. Empty = all. ## `onlyActiveTrends` (type: `boolean`): Skip trends that Google marks as ended. ## `maxTrendingPerGeo` (type: `integer`): 0 = all that Google lists (often 500–1,000 for large countries in 24 hours). ## `language` (type: `string`): Language for place names and date labels (hl), e.g. en-US, es, pt-BR, de. Dates are always in UTC. ## `maxTotalResults` (type: `integer`): Stop after this many charged rows (term × location rows, or trending searches). 0 = no limit. The run's max cost is respected too. ## `maxConcurrency` (type: `integer`): Terms analyzed at the same time. Google Trends limits fast clients: 6 is fast and stable; raise it only if you see no "RATE_LIMITED" retries in the summary. ## `connectDirectFirst` (type: `boolean`): Try a direct connection first (fastest and cheapest) and use the proxy below only for temporary errors. Turn off to send every request through the proxy. ## `proxyConfiguration` (type: `object`): Fallback when Google Trends answers with a temporary error (HTTP 429 or 5xx): Apify datacenter proxy or your own proxy URLs. Residential and SERP groups are not supported (they cost more than the results) and are replaced by datacenter. ## Actor input object example ```json { "searchTerms": [ "coffee", "matcha" ], "geos": [ "US" ], "timeRange": "today 12-m", "mode": "terms", "include": [ "timeline", "regions", "cities", "relatedQueries" ], "category": "0", "property": "web", "trendingGeos": [ "US" ], "trendingHours": "24", "onlyActiveTrends": false, "maxTrendingPerGeo": 0, "language": "en-US", "maxTotalResults": 0, "maxConcurrency": 6, "connectDirectFirst": true, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `overview` (type: `string`): All dataset items, one per term × location: average, latest value, recent and year-over-year change, direction, peak, top region and city, top and rising queries, plus free error rows. ## `timeline` (type: `string`): One row per term and timeline point (date, 0–100 value, partial flag), ready for charts. ## `regions` (type: `string`): One row per term and country, state or metro, highest interest first. ## `cities` (type: `string`): One row per term and city with coordinates, highest interest first. ## `relatedQueries` (type: `string`): One row per top or rising related query, with breakouts and Google Trends links. ## `comparison` (type: `string`): Comparison mode: share of interest per term and regions where each term leads. ## `trendingNow` (type: `string`): "Trending now" mode: trending searches per country with volume, growth, start time and breakdown. ## `summary` (type: `string`): JSON record with the number of terms, results, errors by code, requests, retries and duration. # 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": [ "coffee", "matcha" ], "geos": [ "US" ], "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("cleancut/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": [ "coffee", "matcha", ], "geos": ["US"], "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("cleancut/google-trends-scraper").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 '{ "searchTerms": [ "coffee", "matcha" ], "geos": [ "US" ], "proxyConfiguration": { "useApifyProxy": true } }' | apify call cleancut/google-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,cleancut/google-trends-scraper" } } } ``` 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/uhLutIV1LuI3jsDWI/builds/7yb40jLsqR1SLiZJC/openapi.json