# Google Trends API — Interest, Regions & Queries (`sumitr_mardy/google-trends-scraper`) Actor Google Trends data for a list of search terms: interest over time, interest by country or region, and related queries (top and rising). One flat row per term and country, every field always present, never null. Only complete rows are billed. - **URL**: https://apify.com/sumitr_mardy/google-trends-scraper.md - **Developed by:** [Sumitr Mardy](https://apify.com/sumitr_mardy) (community) - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.60 / 1,000 search terms 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 & Related Queries Give it search terms, get Google Trends back: **interest over time**, **interest by country or region**, and **related queries (top and rising)**. One flat row per search term and country, every field always present, never `null`. Built to be called from pipelines, n8n/Make/Zapier flows and AI agents. **$1 per 1,000 search terms on paid plans, down to $0.60 on Gold, plus $0.0005 per run. No platform usage on top. Rows that fail or have no data are free.** ### Why this one - **It finishes.** The most-used Google Trends actor on the Store completed 55% of its runs in the last 30 days. Google answers HTTP 429 to almost every automated request unless it carries a Google session cookie, from residential IPs too. This actor gets that cookie for each proxy session and retries a blocked request on a fresh one. Measured on Apify: **1,000 of 1,000 search terms** across 20 countries came back complete in 4 minutes 21 seconds. - **The numbers match trends.google.com.** Checked against the live Google Trends page for the same term, country and period: same weekly values, same peak week, same top regions, same related queries. - **One row for every term you send.** A term with almost no searches comes back as `status: "no_data"` (free), not as a missing row, and not as a fake chart. - **You pay for complete rows only.** A row is billed when every section you asked for was fetched. Partial, failed and no-data rows are free. - **Flat and stable.** The same 20 keys on every row. Arrays are always arrays, numbers are numbers. An agent can read `peakDate` or `relatedQueriesRising` without a null check. ### Input | Field | Default | What it does | |---|---|---| | `searchTerms` | — | Search terms, one per item. Required. Each term is looked up on its own, so every row has its own 0–100 scale. | | `geos` | worldwide | Country codes (`US`, `DE`, `VN`) or regions (`US-CA`). Every term is fetched once per entry. | | `timeRange` | `today 12-m` | Past hour, 4 hours, day, 7 days, 30 days, 90 days, 12 months, 5 years, or since 2004. | | `customTimeRange` | — | `YYYY-MM-DD YYYY-MM-DD`; overrides `timeRange`. | | `category` | `0` | Google Trends category ID (e.g. `71` Food & Drink). | | `property` | web | `images`, `news`, `froogle` (Shopping) or `youtube` search instead of web search. | | `interestOverTime` / `interestByRegion` / `relatedQueries` | `true` | Switch sections off to get faster rows. A row is complete when every section you left on was fetched. | | `language` | `en-US` | Language for region names. | ```json { "searchTerms": ["coffee", "matcha"], "geos": ["US", "GB"], "timeRange": "today 12-m" } ``` ### Output One row per search term × country, in completion order. `inputIndex` lines rows up with your input. ```json { "inputIndex": 0, "searchTerm": "coffee", "geo": "US", "timeRange": "today 12-m", "category": 0, "property": "", "status": "ok", "subStatus": "complete", "error": "", "averageInterest": 76, "peakInterest": 100, "peakDate": "2026-04-12T00:00:00.000Z", "latestInterest": 65, "interestOverTime": [{ "date": "2026-10-18T00:00:00.000Z", "value": 65, "isPartial": false }], "interestByRegion": [{ "geoCode": "US-WY", "geoName": "Wyoming", "value": 100 }], "relatedQueriesTop": [{ "query": "coffee near me", "value": 100, "formattedValue": "100" }], "relatedQueriesRising": [{ "query": "home workout routines", "value": 6050, "formattedValue": "Breakout" }], "missing": [], "trendsUrl": "https://trends.google.com/trends/explore?q=coffee&date=today+12-m&hl=en&geo=US", "scrapedAt": "2026-10-26T07:57:10.837Z" } ``` This is a real row from 2026-10-26, shortened: `interestOverTime` has 53 weekly points for 12 months. The odd rising query is what trends.google.com itself shows for "coffee" in the US that day. - Interest values are Google's 0–100 scale: 100 is the term's own peak in that period and place. - `interestByRegion` lists countries when `geo` is worldwide, and states or regions when `geo` is a country. - Rising `value` is percent growth. `"Breakout"` means more than +5,000%. - `averageInterest`, `peakInterest`, `peakDate` and `latestInterest` skip the last, still-filling period (`isPartial: true`). #### Status | `status` | `subStatus` | Charged | |---|---|---| | `ok` | `complete`: every requested section fetched | yes | | `partial` | `section_failed`: one section failed after retries; `missing` names it | free | | `no_data` | `low_search_volume`: Google has too few searches for this term there | free | | `failed` | `blocked`, `network_error`, `invalid_request`, `timeout`, `bad_response`, `cost_limit_reached`, `free_work_limit` | free | ### Pricing | Event | Price | When | |---|---|---| | `search-term` | $1.00 per 1,000 on Bronze, down to $0.60 per 1,000 on Gold ($2.00 per 1,000 on the free plan) | A row with `status: "ok"` | The only other charge is a start fee of $0.0005 per run, which covers the fixed cost of opening a residential proxy session. No platform usage is added on top. A run stops starting new terms when your *maximum cost per run* is reached, and marks the rest `cost_limit_reached`, uncharged. ### Fair use Failed and no-data rows are free, so a run that spends its proxy traffic on terms that keep failing stops starting new ones. The rest come back as `failed` / `free_work_limit`, uncharged, and can be resubmitted. Ordinary lists never get near this. Up to 5,000 term × country pairs per run. ### What it does not do (yet) - **No related topics.** The Google Trends page shows them to signed-in browsers, but Google's data endpoint returns an empty list to every automated caller we tested. Rather than ship an always-empty field, the row leaves it out. - **No multi-term comparison on one scale.** Each term gets its own 0–100 scale. To compare terms against each other, normalise by the values you get, or ask for comparison mode. - **Rising queries are what Google shows, noise included.** On 2026-10-26 trends.google.com itself listed unrelated "Breakout" items ("pet care tips", "best vpn service") as rising queries for evergreen terms such as "coffee" and "electric bike", and a different set on each reload. News-driven and seasonal terms ("hurricane", "diwali") had real ones. Top related queries were relevant in every case we checked. - **No "Trending now" daily list.** This actor answers "how is this term doing"; it does not list today's trending searches. - Google's data is sampled, so values can differ by a point or two between days, as they do on trends.google.com itself. ### Use it from AI agents (MCP) This Actor is a tool on the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp), so Claude, Cursor, VS Code or any MCP client can call it to check how a topic is trending. Load only this tool: a short tool list keeps the agent from picking the wrong one. **Recommended: hosted server, OAuth sign-in (nothing secret on disk).** Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`, …): ```json { "mcpServers": { "google-trends": { "url": "https://mcp.apify.com?tools=sumitr_mardy/google-trends-scraper" } } } ``` **With an API token instead** (clients without OAuth, or unattended setups): ```json { "mcpServers": { "google-trends": { "url": "https://mcp.apify.com?tools=sumitr_mardy/google-trends-scraper", "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" } } } } ``` **Local server (stdio):** ```json { "mcpServers": { "google-trends": { "command": "npx", "args": ["-y", "@apify/actors-mcp-server@latest", "--tools", "sumitr_mardy/google-trends-scraper"], "env": { "APIFY_TOKEN": "YOUR_APIFY_TOKEN" } } } } ``` The hosted server also gives the agent this Actor's output schema, so it knows every field before the first call. `apify mcp install ` writes the config for you if you use the Apify CLI. Get a token at [Apify Console → API & Integrations](https://console.apify.com/settings/integrations), and never commit it. **Tips for agents:** - *"Is X trending up?"*: compare `latestInterest` with `averageInterest`, and read `relatedQueriesRising` for why. - *"Where is X most popular?"*: read `interestByRegion`; it is sorted as Google sorts it, highest first. - Switch off sections you do not need (`interestByRegion: false`, `relatedQueries: false`): fewer requests, faster rows. - Check `status` first. `no_data` means Google has too few searches for the term, which is an answer, not an error. - The MCP `call-actor` tool waits up to 45 seconds; a few terms finish well inside that. For long lists, fetch results with `get-dataset-items` and the run's `datasetId`. ### Use it from code ```python from apify_client import ApifyClient client = ApifyClient("") run = client.actor("sumitr_mardy/google-trends-scraper").call(run_input={ "searchTerms": ["coffee", "matcha"], "geos": ["US"], }) for row in client.dataset(run["defaultDatasetId"]).iterate_items(): print(row["searchTerm"], row["status"], row["latestInterest"], row["peakDate"]) ``` ```bash curl -X POST "https://api.apify.com/v2/acts/sumitr_mardy~google-trends-scraper/run-sync-get-dataset-items?token=" \ -H "Content-Type: application/json" \ -d '{"searchTerms": ["coffee"], "geos": ["US"]}' ``` # Actor input Schema ## `searchTerms` (type: `array`): Search terms to look up, one per item, up to 100 characters each. Each term is looked up on its own (not compared against the others), so each row's values are on that term's own 0–100 scale. Example: \["coffee", "matcha"]. ## `geos` (type: `array`): Where to measure interest: 2-letter country codes ("US", "DE", "VN"), regions ("US-CA"), or leave empty for worldwide. Every search term is fetched once per entry, and each pair is one row. Example: \["US", "GB"]. ## `timeRange` (type: `string`): Period covered by every section. Google picks the resolution: minutes for the past hour, days up to 90 days, weeks for 12 months, months beyond. ## `customTimeRange` (type: `string`): Overrides Time range. Format "YYYY-MM-DD YYYY-MM-DD", e.g. "2025-01-01 2025-06-30". Leave empty to use Time range. ## `category` (type: `integer`): Google Trends category ID to narrow the search, e.g. 71 = Food & Drink, 5 = Computers & Electronics. 0 = all categories. ## `property` (type: `string`): Which Google search to measure. Default is web search. ## `interestOverTime` (type: `boolean`): Include interestOverTime: the 0–100 interest series for the time range, plus averageInterest, peakInterest, peakDate and latestInterest. ## `interestByRegion` (type: `boolean`): Include interestByRegion: 0–100 interest per country (worldwide), or per state/region (when a country is given). ## `relatedQueries` (type: `boolean`): Include relatedQueriesTop and relatedQueriesRising: what people also searched for. Rising values are percent growth; "Breakout" means more than +5000%. ## `language` (type: `string`): Interface language for region names, e.g. "en-US", "de", "ja". Does not change which searches are counted. ## Actor input object example ```json { "searchTerms": [ "coffee" ], "geos": [ "US" ], "timeRange": "today 12-m", "category": 0, "property": "", "interestOverTime": true, "interestByRegion": true, "relatedQueries": true, "language": "en-US" } ``` # 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 = { "searchTerms": [ "coffee" ], "geos": [ "US" ] }; // Run the Actor and wait for it to finish const run = await client.actor("sumitr_mardy/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"], "geos": ["US"], } # Run the Actor and wait for it to finish run = client.actor("sumitr_mardy/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" ], "geos": [ "US" ] }' | apify call sumitr_mardy/google-trends-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,sumitr_mardy/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/Lp5TXDA9GebT6DT2x/builds/UQASIinEM6FQ79wAL/openapi.json