# Google Trends Scraper & API (`cleanpull/google-trends-scraper`) Actor Google Trends API alternative for any number of terms: interest over time by country, region, city or metro, related queries and topics, Trending Now, and calibrated comparisons beyond 5 terms. Daily data across years. From $1.50 per 1,000 results; compact JSON for AI agents. - **URL**: https://apify.com/cleanpull/google-trends-scraper.md - **Developed by:** [CleanPull](https://apify.com/cleanpull) (community) - **Categories:** SEO tools, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.10 / 1,000 term 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 Scraper & API Get Google Trends data for any number of search terms in one run: interest over time, interest by country, region, city or metro area, related queries, side-by-side comparisons, and Trending Now with search volumes. Rank more than 5 terms on one calibrated scale, and get daily points across multi-year ranges. Clean, typed JSON or flat rows, built for AI agents and data teams, from **$1.50 per 1,000 results**. ### What you can do with it - **Track a keyword portfolio**: "Get Google Trends interest for these 50 keywords in the US over the past 12 months." - **Rank many terms against each other**: "Which of these 30 product names gets the most searches?" Calibrated comparison puts every term on one 0-100 scale with error bounds, beyond Google's 5-term limit. - **Compare across countries**: "How does interest in electric cars compare in the US, UK and Germany?" One run, any number of locations. - **Find rising topics**: "What related searches are breaking out around web scraping?" Rising queries are flagged with `isBreakout`. - **Watch what is trending**: "What is trending in the UK in sports right now?" Hundreds of trends with search volume, growth and start time, not just the top 10. - **Monitor on a schedule**: monitor mode returns only new trends or new rising queries since the last run. - **Feed an AI agent or dashboard**: choose only the fields you need, or get one flat row per data point. ### Why this actor - **Reliable and fast.** Plain HTTP requests with automatic session rotation and proxy escalation; no browser, no hanging runs. A blocked data type is reported in `missingDataTypes` instead of failing the run. - **Every data type in one record per term**, plus a computed `summary`: average, peak and date, latest value, change in percent and direction (rising, falling, stable). - **Calibrated comparison of any number of terms** with low and high bounds, so you know how precise each value is. - **Daily points for long ranges.** Google returns weekly or monthly points beyond about 9 months; turn on `dailyResolution` for one point per day across years. - **Standard Google Trends field names** (`interestOverTime_timelineData`, `interestBySubregion`, `relatedQueries_rising` and so on), so existing pipelines keep working. - **Built for AI agents**: typed inputs with defaults and examples, a declared output schema, `fields` selection, and a `RUN_SUMMARY` with the outcome of every lookup. Works through Apify's MCP server. ### Modes | Mode | What you get | Billed per | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | `explore` (default) | One record per term (and per location): interest over time, by region, related queries, optional topic suggestions; with `compare`, an extra comparison record per group of up to 5 terms | Term record, comparison record | | `calibrated-comparison` | One record per term with its rank, `relativeInterest` (largest term = 100), `low` and `high` bounds, and its time series on the shared scale | Calibrated term | | `trending` | Trending Now for a country: term, search volume, growth percent, start and end time, active flag, categories, related searches | Trending item | ### Input | Field | Type | What it does | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------- | | `mode` | `explore`, `calibrated-comparison`, `trending` | What to get (default `explore`) | | `searchTerms` | array of strings | Terms to look up, any number | | `startUrls` | array of Google Trends explore URLs | Terms, locations, period, category and search type read from each URL | | `compare` | boolean | Compare terms on one scale in groups of up to 5, with a comparison record | | `geo` | string | `US`, `GB`, `US-CA`, `US-CA-807`; empty = worldwide | | `geos` | array of strings | Run every term for each location, e.g. `["US", "GB", "DE"]` | | `timeRange` | `past-hour` … `all-time` | Preset period (default `past-12-months`) | | `customTimeRange` | string | `"2024-01-01 2024-12-31"` or hourly `"2026-09-01T00 2026-09-03T12"` | | `category` | integer | Google Trends category id (0 = all) | | `property` | `web`, `images`, `news`, `youtube`, `shopping` | Which Google search to measure | | `dataTypes` | array | `interestOverTime`, `interestByRegion`, `relatedQueries`, `relatedTopics`, `suggestions` | | `regionResolution` | `auto`, `country`, `region`, `city`, `metro` | Detail of the region breakdown | | `includeLowVolumeRegions` | boolean | Include regions Google hides for low volume | | `dailyResolution` | boolean | Daily points across ranges longer than about 9 months | | `trendingGeo`, `trendingHours`, `trendingCategories`, `trendingActiveOnly`, `trendingMaxItems` | | Trending Now: country, window (4, 24, 48 or 168 hours), categories, active only, how many | | `monitorMode`, `monitorName` | boolean, string | Only new trends or new rising queries since the last run | | `outputFormat` | `nested`, `flat` | One record per term, or one row per data point | | `fields` | array of strings | Return only these fields (dotted paths allowed) | | `maxItems` | integer | Stop after this many billed results | | `language`, `timezone` | string, integer | Labels language (`en-US`) and offset in minutes for hourly data | #### Example input ```json { "searchTerms": ["web scraping", "data extraction"], "compare": true, "geos": ["US", "GB"], "timeRange": "past-12-months", "dataTypes": ["interestOverTime", "interestByRegion", "relatedQueries"] } ``` ### Output #### Term record (explore mode, shortened) ```json { "type": "term", "searchTerm": "web scraping", "geo": "US", "timeRange": "past-12-months", "summary": { "average": 67.8, "peak": 100, "peakDate": "2026-06-07T00:00:00.000Z", "latest": 24, "latestDate": "2026-09-27T00:00:00.000Z", "changePercent": -44, "direction": "falling" }, "interestOverTime_timelineData": [ { "date": "2026-09-27T00:00:00.000Z", "formattedTime": "Sep 27 – Oct 3, 2026", "value": [24], "hasData": [true], "isPartial": false } ], "interestOverTime_averages": [68], "interestBySubregion": [{ "geoCode": "US-MD", "geoName": "Maryland", "value": [100] }], "relatedQueries_top": [{ "query": "ai web scraping", "value": 100, "isBreakout": false }], "relatedQueries_rising": [ { "query": "best noise cancelling headphones", "value": 12150, "formattedValue": "Breakout", "isBreakout": true } ], "missingDataTypes": [], "trendsUrl": "https://trends.google.com/trends/explore?q=web%20scraping&geo=US&date=today%2012-m" } ``` #### Calibrated term Each calibrated record also carries `timeline`: the term's series rescaled onto the shared scale. ```json { "type": "calibrated-term", "rank": 4, "searchTerm": "selenium", "relativeInterest": 0.2263, "low": 0.1683, "high": 0.2937, "belowRange": false, "bridge": "python", "comparedTerms": 12 } ``` #### Trending item ```json { "type": "trending", "rank": 1, "term": "bahrain grand prix", "geo": "GB", "searchVolume": 100000, "growthPercent": 300, "startedAt": "2026-10-04T06:40:00.000Z", "isActive": true, "categories": [{ "id": 17, "name": "Sports" }], "trendBreakdown": ["bahrain grand prix"] } ``` Every run also writes `RUN_SUMMARY` to the key-value store: the outcome (`COMPLETE`, `PARTIAL`, `NO_NEW_DATA`, `EMPTY` or `FAILED`), counts, and the reason for any failed lookup. ### Pricing Pay only for results delivered. Blocked or failed lookups are never charged. | Result | Free and Bronze | Silver | Gold | | ---------------------------------------------------------------- | --------------- | ------ | ----- | | Term record (all requested data types for one term and location) | $1.50 | $1.30 | $1.10 | | Comparison record | $1.50 | $1.30 | $1.10 | | Calibrated term | $10.00 | $9.00 | $8.00 | | Trending item | $1.00 | $0.90 | $0.80 | Prices are per 1,000 results; your tier depends on your Apify plan. Each run also has a $0.00005 start fee. Flat mode is billed per term record, not per row. ### How calibrated comparison works Google compares at most 5 terms at a time, each group on its own 0-100 scale rounded to whole numbers. The actor first sizes every term against one anchor, then chains groups from the most popular term down, each group sharing a "bridge" term with the previous one and holding only terms of similar size, so no value is lost to rounding. Bounds carry Google's rounding through the chain: a niche term 30,000 times smaller than the top one still comes back with a value and a range. ### Limits - **Related topics** are returned only when Google provides them to logged-out visitors, which is often not the case. When they are missing, the record says so in `missingDataTypes`. - Google Trends values are relative (0-100), not absolute search counts. Trending Now volumes are Google's own approximate figures. - Calibrated values are only as precise as their bounds; terms far apart in popularity have wider bounds. - **Memory:** explore runs fit in 512 MB at any size tested (2,000 terms); calibrated comparisons of up to about 500 terms fit in 512 MB (5 years of daily points), larger ones need the default 4,096 MB. - **Nothing found**: terms with no interest data, or input naming nothing to look up, are not a failure: the run still succeeds, with one free `recordType: "unreadable"` row giving the `reason`; nothing is charged. A run near its time limit stops starting lookups, delivers what it read and lists the rest in RUN_SUMMARY. ### Changelog - **0.1.x, reliability** (2026-10-24): runs that find nothing (terms without data, input naming nothing to look up) end SUCCEEDED with a free `unreadable` row saying why, instead of FAILED; custom time ranges and Trends URLs are checked in the input form; a run stops starting lookups before its time limit, never TIMED-OUT. A run whose every lookup Google blocked still fails. Prices and events unchanged. - **0.1** (October 2026): explore, comparison, multiple locations, calibrated comparison of any number of terms, daily points for long ranges, Trending Now, monitor mode, flat output and field selection. # Actor input Schema ## `mode` (type: `string`): Explore returns Google Trends data for each term. Calibrated comparison ranks any number of terms on one shared scale (Google compares at most 5 at a time), with error bounds and rescaled time series. Trending Now returns what is trending in a country, with search volume and growth. ## `searchTerms` (type: `array`): Terms to look up, one per line (any number). Each term gets its own record. Example: \["web scraping", "data extraction"]. ## `startUrls` (type: `array`): Optional. Google Trends explore URLs (trends.google.com/trends/explore?q=...). Terms, countries, period, category and search type are read from each URL. ## `compare` (type: `boolean`): Compare your terms against each other on Google's shared 0-100 scale, in groups of up to 5 (Google's limit per comparison). Adds a comparison record with the winner, averages and the leading term in each region. ## `geo` (type: `string`): Where to measure interest. Empty = worldwide. A country code (US, GB, DE), a state or region (US-CA, GB-ENG) or a US metro (US-CA-807). ## `geos` (type: `array`): Optional. Run every term for each of these locations in one run, for example \["US", "GB", "DE"]. Overrides Location. ## `timeRange` (type: `string`): The period to measure. Shorter periods give finer points (minutes, hours, days); longer ones give weeks or months. ## `customTimeRange` (type: `string`): Optional, overrides Time range. Dates as "2024-01-01 2024-12-31", or hours as "2026-09-01T00 2026-09-03T12". ## `category` (type: `integer`): Optional Google Trends category id to narrow ambiguous terms (0 = all categories). Top-level ids: 3 Arts & Entertainment, 47 Autos & Vehicles, 44 Beauty & Fitness, 22 Books & Literature, 12 Business & Industrial, 5 Computers & Electronics, 7 Finance, 71 Food & Drink, 8 Games, 45 Health, 65 Hobbies & Leisure, 11 Home & Garden, 13 Internet & Telecom, 958 Jobs & Education, 19 Law & Government, 16 News, 299 Online Communities, 14 People & Society, 66 Pets & Animals, 29 Real Estate, 533 Reference, 174 Science, 18 Shopping, 20 Sports, 67 Travel. ## `property` (type: `string`): Which Google search to measure. ## `dataTypes` (type: `array`): What to collect for each term. Fewer types make runs faster. Related topics are returned only when Google provides them to logged-out visitors, which is often not the case. ## `regionResolution` (type: `string`): How fine the interest-by-region breakdown is. ## `includeLowVolumeRegions` (type: `boolean`): Include regions with little search volume, which Google hides by default. ## `dailyResolution` (type: `boolean`): For ranges longer than about 9 months, Google returns weekly or monthly points. Turn this on to get one point per day across the whole range, stitched from overlapping daily windows (one extra request per 7 months of range). ## `trendingGeo` (type: `string`): Country for Trending Now. ## `trendingHours` (type: `string`): How far back Trending Now looks. ## `trendingCategories` (type: `array`): Optional. Only trends in these categories. ## `trendingActiveOnly` (type: `boolean`): Only trends that are still rising (not ended). ## `trendingMaxItems` (type: `integer`): How many trends to return, highest volume first (0 = all Google lists, often several hundred). ## `monitorMode` (type: `boolean`): Return only what is new since the previous run with the same monitor name: new trending searches, or new rising queries for your terms. Use with a schedule. ## `monitorName` (type: `string`): Keeps separate memories for separate monitors (for example "us-tech"). ## `outputFormat` (type: `string`): Nested keeps each term's data together; flat gives one row per date, region or related query. ## `fields` (type: `array`): Optional. Return only these fields (dotted paths allowed, such as summary.average) to keep output small for AI agents. Empty = everything. ## `maxItems` (type: `integer`): Stop after this many billed results (term records, comparisons or trending items). Caps the cost of a run. ## `language` (type: `string`): Language for names and labels, such as en-US or de. ## `timezone` (type: `integer`): Minutes west of UTC for hourly data (0 = UTC, 300 = New York in winter). ## Actor input object example ```json { "mode": "explore", "searchTerms": [ "web scraping" ], "compare": false, "geo": "", "timeRange": "past-12-months", "category": 0, "property": "web", "dataTypes": [ "interestOverTime", "interestByRegion", "relatedQueries" ], "regionResolution": "auto", "includeLowVolumeRegions": false, "dailyResolution": false, "trendingGeo": "US", "trendingHours": "24", "trendingActiveOnly": false, "trendingMaxItems": 100, "monitorMode": false, "monitorName": "default", "outputFormat": "nested", "maxItems": 1000, "language": "en-US", "timezone": 0 } ``` # Actor output Schema ## `results` (type: `string`): Every record: term records, comparisons or trending items (or flat rows). ## `overview` (type: `string`): No description ## `trending` (type: `string`): No description ## `runSummary` (type: `string`): Outcome (COMPLETE, PARTIAL, NO_NEW_DATA, EMPTY, FAILED), counts and any failed lookups. ## `calibrated` (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 = { "searchTerms": [ "web scraping" ] }; // Run the Actor and wait for it to finish const run = await client.actor("cleanpull/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": ["web scraping"] } # Run the Actor and wait for it to finish run = client.actor("cleanpull/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": [ "web scraping" ] }' | apify call cleanpull/google-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,cleanpull/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/xFvleTX82l8RiUeS2/builds/fIg2i9ZWnbxtDUMWW/openapi.json