# Google Trends API – Interest, Regions & Related (`datarelay/google-trends-api`) Actor Google Trends data at scale: interest over time, by region, related queries and related topics. Compare unlimited terms on one scale, across countries or years, get daily data for 5+ years, plus Google's methodology notes. - **URL**: https://apify.com/datarelay/google-trends-api.md - **Developed by:** [DataRelay](https://apify.com/datarelay) (community) - **Categories:** SEO tools, Marketing, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $1.11 / 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 API – Interest, Regions & Related Get **Google Trends data at scale** – interest over time, interest by region, related queries and **related topics** – for any number of search terms, with comparisons Google's own UI cannot do. ### What makes it different - **Compare unlimited terms on one scale.** Google compares at most 5 terms; this Actor chains batches through an anchor term so 20 or 200 terms stay comparable. - **Same term across countries or years on one scale** – e.g. `bitcoin` in US vs DE vs PL, or Black Friday 2024 vs 2025. - **Daily data for 5+ years** (or hourly data for weeks): overlapping windows are stitched onto one 0–100 scale. - **Related topics that actually return data** – 20 of 20 terms in our last measurement (2026-10-20), where other Google Trends Actors we measured returned empty lists – with topic ids you can reuse as search terms. - **Topics as input** – use `/m/0k8z` (Apple – Technology company) instead of an ambiguous word; mode `suggest` finds the ids. - **All 1,426 categories, 3,600+ locations** (countries, states, US metro areas, cities) and all search types: web, images, news, shopping, YouTube. - **What people search for without a keyword** – top and rising queries for a country and category. - **Google's methodology notes** (`dataNotes`) – the "Note" markers that explain jumps caused by changes in Google's data collection. - **Honest results:** every term gets a `status` (`ok`, `no_data`, `blocked`, `error`). You pay only for terms with data; the run stops on time (`maxRunSecs`) with partial results instead of hanging. ### Who uses it - **SEO and content teams** – which keywords are growing, where, and what people search for next (rising queries and topics). - **Market research and product teams** – compare brands, products or categories across countries and years on one scale. - **E-commerce** – seasonality: when demand for a product starts, peaks and fades, by state or city. - **Finance and data science** – long daily series of search interest as a signal for models and dashboards. - **AI agents and automations** – a documented input schema, one row per term with a status, and a run summary for decisions. ### Quick start ```json { "searchTerms": ["bitcoin", "ethereum"], "geo": "US", "timeRange": "past-12-months" } ``` More examples: | Goal | Input | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | 10 brands on one scale | `{"searchTerms": ["nike","adidas","puma","asics","reebok","new balance","under armour","fila","vans","converse"], "comparison": "together"}` | | One term in three countries | `{"searchTerms": ["ozempic"], "comparison": "acrossGeos", "geos": ["US","GB","DE"]}` | | Year over year | `{"searchTerms": ["black friday"], "geo": "US", "comparison": "acrossTimes", "timeRanges": ["2024-10-01 2024-12-31", "2025-10-01 2025-12-31"]}` | | Daily data for 5 years | `{"searchTerms": ["chatgpt"], "timeRange": "past-5-years", "granularity": "daily"}` | | Trending searches in a category | `{"geo": "US", "category": 71}` (no search terms) | | YouTube searches by US metro area | `{"searchTerms": ["minecraft"], "geo": "US", "property": "youtube", "regionResolution": "DMA"}` | | States, cities and metros at once | `{"searchTerms": ["coffee"], "geo": "US", "regionResolution": "REGION", "extraRegionResolutions": ["CITY", "DMA"]}` | | Safe limit for long lists | `{"spreadsheetUrl": "https://docs.google.com/spreadsheets/d//edit", "maxTerms": 500}` | | Re-run a link from the browser | `{"startUrls": [{"url": "https://trends.google.com/trends/explore?q=pizza&geo=IT"}]}` | | Terms from a spreadsheet | `{"spreadsheetUrl": "https://docs.google.com/spreadsheets/d//edit"}` (shared as "anyone with the link") | | Find topic ids | `{"mode": "suggest", "searchTerms": ["apple", "jaguar"]}` | | List categories / locations | `{"mode": "reference", "referenceType": "geos"}` | Search operators work as in Google Trends: `"exact phrase"`, `tennis + squash` (either), `jaguar -car` (exclude). ### Output One row per term (layout `nested`). A real result (run of 2026-10-16, arrays shortened with "…"; full run: 53 weekly points, 51 regions (states + DC), 25 + 25 related queries, 25 + 18 related topics): ```json { "term": "solar panels", "termType": "query", "geo": "US", "timeRange": "today 12-m", "category": 0, "property": "web", "comparison": "separate", "comparedWith": [], "status": "ok", "average": 35.34, "peak": 100, "peakDate": "2026-08-09", "latest": 27, "changePct": 15.9, "direction": "rising", "timeline": [ { "date": "2025-10-12", "value": 27, "hasData": true, "isPartial": false }, { "date": "2025-10-19", "value": 23, "hasData": true, "isPartial": false }, "…", { "date": "2026-10-11", "value": 24, "hasData": true, "isPartial": true } ], "dataNotes": [], "regions": [ { "geoCode": "US-WY", "geoName": "Wyoming", "value": 100 }, { "geoCode": "US-KS", "geoName": "Kansas", "value": 82 }, "…" ], "relatedQueries": { "top": [ { "title": "solar panels cost", "value": 100, "formattedValue": "100" }, { "title": "solar panel", "value": 60, "formattedValue": "60" }, "…" ], "rising": [ { "title": "flooded solar panels arc raiders", "value": 7800, "formattedValue": "Breakout", "isBreakout": true }, "…" ] }, "relatedTopics": { "top": [ { "title": "Solar energy", "mid": "/m/06xbd", "topicType": "Topic", "value": 100 }, { "title": "Solar panel", "mid": "/m/0fnrbc", "topicType": "Topic", "value": 84 }, "…" ], "rising": [ { "title": "Solar panel", "mid": "/m/0fnrbc", "topicType": "Topic", "formattedValue": "Breakout" }, "…" ] }, "warnings": [], "trendsUrl": "https://trends.google.com/trends/explore?date=today+12-m&geo=US&q=solar+panels", "scrapedAt": "2026-10-16T10:04:05.553Z" } ``` Every row has a stable **`id`**: the same term in the same comparison gets the same id in every run, so scheduled runs can be deduplicated or upserted. Additional region resolutions come in `regionsByResolution`. Layout `flat` gives **one row per data point** – timeline dates, regions, related queries and related topics, told apart by `rowType` – ready for Google Sheets, Excel or BI tools. Each flat row has its own stable `id` too. Each run also stores a **summary** in the `OUTPUT` record of its key-value store (items per status, related topics blocked, why the run stopped, charged events) – one read for integrations and AI agents. **Metrics:** `average` and `peak` over the period, `latest` complete value, `changePct` = average of the last quarter of the period vs. the quarter before it, `direction` = `rising` / `falling` (±10 %) or `stable`. Values are relative (0–100) as in Google Trends: each point is the share of all searches in that place and time, scaled to the highest point of the comparison – not a number of searches. In `acrossGeos` a higher value means a larger share of searches in that country, not more searches. Stitched and anchored series keep two decimals. ### Integrations - **API:** `POST https://api.apify.com/v2/acts/datarelay~google-trends-api/run-sync-get-dataset-items` with the input as JSON body. - **AI agents (MCP):** add the Actor in the [Apify MCP server](https://mcp.apify.com) – every input field is documented for the model. - **n8n / Make / Zapier:** use the Apify integration, action "Run Actor", then read the dataset items. - **Schedules:** run daily/weekly with the same input and get only fresh data. ### Pricing – what a job costs You pay only for results with data; platform usage is included (no compute or proxy costs on top). | Event | Price (FREE / BRONZE) | When | | ---------------- | --------------------- | ---------------------------------------------------------------------------- | | `run-start` | $0.02 | once per run, together with the first paid result | | `term` | $1.20 / 1,000 | term with data: timeline, regions, related queries | | `related-topics` | $10 / 1,000 | term whose related topics came back (not charged when they stay blocked) | | `term-window` | $1 / 1,000 | each extra window of daily / hourly data over long ranges | | `flat-row` | $0.01 / 1,000 | each row of the `flat` layout (a term with all sections ≈ 200 rows ≈ $0.002) | | `suggestion` | $0.50 / 1,000 | suggest lookup that found topics | SILVER and GOLD plans get lower `term`, `term-window` and `suggestion` prices (−3 to −8 %). `reference` mode is free. | Typical job | Cost | | ---------------------------------------------------- | ------ | | 1 term, 12 months, all sections incl. related topics | $0.031 | | 1 term without related topics | $0.021 | | 100 terms with related topics | $1.14 | | 100 terms without related topics | $0.14 | | 10 terms on one scale (timeline, regions, queries) | $0.032 | | Daily data for 5 years, 1 term (10 windows) | $0.030 | **You don't pay** for terms without data (`no_data`), blocked or failed terms, related topics that stayed blocked, or a run that returns no paid result (no start fee either). ### Reliability (measured) - Load test of 2026-10-27 (112 runs, 306 terms, real inputs at 10× our expected traffic): **98.7 % of timelines, 98.6 % of regions and related queries and 96 % of related topics delivered**. The rest were terms Google rate-limited on every attempt; they are reported with `status: "blocked"` (or a section warning) and not charged. - Related topics come only through Google's embed path, which refuses some IPs. The Actor retries on other IPs, tries once more at the end of the run (at least 30 s later – blocks come in waves) and, if that fails too, delivers the term with the warning `relatedTopics: blocked` (and does not charge `related-topics`). - Speed: a run with 1–5 terms takes ~10 s (median); 20 terms take ~1 minute without related topics and ~2 minutes with them (measured 2026-10-27: 55 s and 135 s, all 20 terms delivered). - Scheduled control runs check the Actor every hour, with alerts on Google's rate limits. ### Limits and good to know - **Values are relative** (0–100), not search counts – see Output. Compare terms only within one comparison (`together`, `acrossGeos`, `acrossTimes`). - Google rate-limits by IP. By default the Actor uses **Apify residential proxies**: each term runs on its own IP, and when Google blocks it the term continues on a fresh IP from where it stopped (never on the blocked one); the last attempts use your default Apify Proxy. If your account cannot use residential proxies, the run uses your default Apify Proxy (more blocks on large runs). - When a section stays blocked after all retries, the term is still delivered with a warning such as `relatedTopics: blocked` or `regions: blocked`; only a blocked timeline makes the term `blocked` (not charged). Terms with blocked related topics are delivered at the end of the run, after one more try. - When Google blocks every term of a run, the run still finishes as succeeded, with a `blocked` row per term, the status message "No results…" and `outcome: "no_results"` in the `OUTPUT` summary – nothing is charged; try again later. - **More than 5 terms on one scale:** terms are compared in batches of 5 linked through an anchor term, chosen automatically (the first term, or the most popular one when the first is too rare – a few extra requests). Terms thousands of times less popular than the top term show 0, as they would in Google Trends. - `acrossTimes` compares **at most 5 periods** (Google puts at most 5 on one scale). - Google computes Trends from a sample: the same request can return slightly different values on different runs. - Google's **rising** lists sometimes contain unrelated or spam-like breakout queries (e.g. "home workout routines" for coffee in one of our runs) – Google's data, not an Actor error; filter them if you use them automatically. - Google returns integers; very small terms may show `0` with `hasData: false` (too little data). ### FAQ **Does it give search volumes?** No – Google Trends gives relative interest (0–100), not counts: see Output. For volume ranges of trending searches ("20K+"), use our [Google Trending Now](https://apify.com/datarelay/google-trending-now) Actor. **Why not pytrends or my own script?** They run from your IP, and Google blocks it after a few dozen requests. This Actor spreads requests over residential IPs, retries blocked requests on fresh ones, compares more than 5 terms on one scale and returns related topics. **Why do two runs give slightly different values?** Google computes Trends from a sample of searches, so the same request can differ by a few points between runs. Trends and shapes stay the same. **What does `blocked` mean?** Google rate-limited every attempt for that term. You are not charged; run it again later (blocks usually pass within minutes to hours). **How do I get the data into Google Sheets or Excel?** Use layout `flat` (one row per data point) and export the dataset as CSV / Excel, or add Apify's Google Sheets integration. Terms can also come from a sheet (`spreadsheetUrl`). **Can I schedule it?** Yes – create a task with your input and a schedule; stable row `id`s let you deduplicate or upsert results. ### Not affiliated with Google This is an independent Actor by DataRelay, not Google's official Google Trends API (which is in a limited alpha). It reads the same data that the public Google Trends website shows. ### Usage statistics The Actor sends anonymous run statistics to the developer (mode and options, number of items and their statuses, Google request counts, duration). Search terms and your Apify user id are never sent – only keyed hashes, used to count repeated queries and distinct users. No results, account details or personal data are collected. ### Changelog - 0.1 – first version. # Actor input Schema ## `mode` (type: `string`): `explore` – Google Trends data for search terms (default). `suggest` – find topic ids for terms (e.g. "Apple – Technology company"), usable as search terms. `reference` – list of all category ids or location codes. ## `searchTerms` (type: `array`): Search terms or topic ids (`/m/0k8z`) to analyze. Google search operators work: `"exact phrase"`, `a + b` (or), `-word` (exclude). Leave empty to get what people search for in the chosen location and category (top and rising queries). ## `startUrls` (type: `array`): Explore URLs copied from trends.google.com (each URL is one comparison, with its own location, time and category). ## `spreadsheetUrl` (type: `string`): Link to a Google Sheet shared as "Anyone with the link can view". Search terms are read from the first column (a header like "keyword" is skipped). ## `comparison` (type: `string`): `separate` – each term on its own 0–100 scale. `together` – all terms on one scale (any number of terms; more than 5 are combined through an anchor term, chosen automatically). `acrossGeos` – each term in several locations on one scale. `acrossTimes` – each term in several periods on one scale (e.g. year over year). ## `geo` (type: `string`): Country (`US`), region (`US-CA`) or metro (`US-CA-803`) code. Empty = worldwide. Use mode `reference` with `geos` to list all 3,600+ codes. ## `geos` (type: `array`): For comparison `acrossGeos`: location codes compared on one scale, e.g. `US`, `DE`, `PL`. ## `timeRange` (type: `string`): Period of the data. Choose `custom` to set start and end dates. ## `startDate` (type: `string`): For a custom time range: `YYYY-MM-DD`, or `YYYY-MM-DDTHH` for hourly precision (UTC). ## `endDate` (type: `string`): For a custom time range: `YYYY-MM-DD`, or `YYYY-MM-DDTHH` for hourly precision (UTC). ## `timeRanges` (type: `array`): For comparison `acrossTimes`: periods as `YYYY-MM-DD YYYY-MM-DD` (or presets like `past-12-months`), e.g. `2024-10-01 2024-12-31` and `2025-10-01 2025-12-31`. 2–5 periods (Google compares up to 5 on one scale). ## `granularity` (type: `string`): Google returns weekly or monthly points for long ranges. `daily` / `hourly` fetch overlapping windows and stitch them onto one scale (works with comparison `separate`; each extra window is charged). ## `category` (type: `integer`): Google Trends category (0 = all). Examples: 7 Finance, 71 Food & Drink, 5 Computers & Electronics, 958 Jobs. Mode `reference` lists all 1,426 categories. ## `property` (type: `string`): Which Google search to analyze. ## `includeTimeline` (type: `boolean`): Timeline with values 0–100 plus metrics (average, peak, recent change, direction) and Google's methodology notes. ## `includeRegions` (type: `boolean`): Where the term is most popular. ## `regionResolution` (type: `string`): `auto` = countries for worldwide, regions for a country. `CITY` gives cities; `DMA` = US metro areas. ## `extraRegionResolutions` (type: `array`): Further resolutions in the same run, e.g. `CITY` and `DMA` besides states – one extra request each, returned in `regionsByResolution` (no extra charge). ## `includeLowVolumeRegions` (type: `boolean`): Also return regions with little search volume. ## `includeRelatedQueries` (type: `boolean`): Top and rising queries searched together with the term. ## `includeRelatedTopics` (type: `boolean`): Top and rising topics (entities) related to the term, with topic ids. ## `outputLayout` (type: `string`): `nested` – one row per term with all data. `flat` – one row per term and date (best for spreadsheets). ## `referenceType` (type: `string`): For mode `reference`: which list to return. ## `language` (type: `string`): Language of topic names and labels, e.g. `en-US`, `de`, `pl`. ## `timezoneOffset` (type: `integer`): Google's timezone offset in minutes (0 = UTC, -60 = UTC+1, 300 = UTC-5). Affects hourly data. ## `maxTerms` (type: `integer`): Safety limit for long lists (e.g. from a spreadsheet or an AI agent): terms above it are not processed. 0 = no limit. ## `maxConcurrency` (type: `integer`): How many terms are processed in parallel. Higher is faster but more likely to hit Google's rate limits. ## `maxRunSecs` (type: `integer`): Stop starting new terms after this time and finish with partial results (0 = only the run timeout applies). ## `proxyConfiguration` (type: `object`): Google rate-limits by IP. Default: Apify residential proxies with a new IP for every unit of work (most reliable). If your account cannot use residential proxies, the run falls back to your default Apify Proxy. ## Actor input object example ```json { "mode": "explore", "searchTerms": [ "bitcoin" ], "startUrls": [], "comparison": "separate", "geo": "US", "geos": [], "timeRange": "past-12-months", "timeRanges": [], "granularity": "native", "category": 0, "property": "web", "includeTimeline": true, "includeRegions": true, "regionResolution": "auto", "extraRegionResolutions": [], "includeLowVolumeRegions": false, "includeRelatedQueries": true, "includeRelatedTopics": true, "outputLayout": "nested", "referenceType": "categories", "language": "en-US", "timezoneOffset": 0, "maxTerms": 0, "maxConcurrency": 3, "maxRunSecs": 0, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `results` (type: `string`): No description ## `summary` (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": [ "bitcoin" ], "geo": "US", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("datarelay/google-trends-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 = { "searchTerms": ["bitcoin"], "geo": "US", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("datarelay/google-trends-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 '{ "searchTerms": [ "bitcoin" ], "geo": "US", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call datarelay/google-trends-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,datarelay/google-trends-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/Q0vaOx0JjnqDmIcZu/builds/PbWp6Rp7dOkK5FK1i/openapi.json