# Google Trends Scraper: Compare 100+ Keywords, Rising & Trending (`chaptersoft/google-trends-reliable`) Actor Reliable Google Trends API: compare 100+ keywords on one 0–100 scale (auto-anchored), interest over time, by region/metro/city, top & rising queries, Trending Now with news, and change alerts. Flat, LLM-ready JSON. Pay per result, no start fee. - **URL**: https://apify.com/chaptersoft/google-trends-reliable.md - **Developed by:** [Jeremy Lam](https://apify.com/chaptersoft) (community) - **Categories:** SEO tools, Marketing, News - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.75 / 1,000 term reports 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: Compare 100+ Keywords, Regions, Rising Queries & Trending Now **Get Google Trends data that actually arrives.** This Actor collects interest over time, interest by **country, state, metro (DMA) and city**, **top and rising related queries** (with breakouts), and **Google Trending Now** searches with volume and news articles. It can put **any number of keywords on one comparable 0–100 scale**: Google allows 5 terms per comparison, and the Actor anchors the rest automatically. It runs without a browser and handles rate limits (HTTP 429) for you. There is **no start fee**, and **failed terms are never charged**. The output is flat, documented JSON and CSV that works in spreadsheets, BI tools and AI agents (MCP). ### Why this Google Trends scraper | | This Actor | Typical Google Trends scrapers | |---|---|---| | **More than 5 keywords on one scale** | ✅ Automatic anchoring and bridging. 100+ terms on one scale, with a scale-quality label on every term | ❌ 5 per request, or "add your own anchor term" | | **Rate limits (HTTP 429)** | ✅ Adaptive pacing, backoff with jitter, fresh sessions and automatic proxy escalation (none → datacenter → residential). Proxy cost is included | Runs fail, hang or return empty data | | **Related queries** | ✅ Top and rising, growth %, breakout flag and an **on-topic flag** (Google mixes generic queries into rising lists) | Often missing | | **Regions** | ✅ Several levels in one run (states, metros and cities) and a low-volume toggle | Usually one level | | **Trending Now** | ✅ Hundreds of trends per country (4 h / 24 h / 48 h / 7 days), categories, active-only filter, volume, growth, start/end time, related searches and **up to 3 news articles for every trend** | RSS feed only (about 10 items) | | **Monitoring** | ✅ New rising queries, breakouts, direction changes, top-region changes, jumps and drops. "Only new/changed" output mode | Rare | | **Failed terms** | ✅ Error item with a reason and a retry hint, **never charged** | Silently missing, or charged anyway | | **Price** | ✅ **$1.50 per 1,000 term reports** (down to $0.75 on Business plans), **no start fee**, platform and proxy usage included | $2–$25 per 1,000, often with a start fee or browser usage billed on top | ### What you can use it for - **SEO and content planning:** rank 50–500 keyword ideas on one scale, find breakout queries before they get competitive, and plan around seasonal peaks. - **Market and product research:** compare brands, products or categories over 5 years, and see which states, metros or cities search the most. - **E-commerce and ads:** time campaigns to demand, and spot rising product queries such as "hoka women's transport 2" (+3,350%). - **Newsrooms and social media:** pull a daily Trending Now feed per country, with volume, categories and the news stories behind each trend. - **Monitoring and alerts:** schedule a weekly run and get only what changed (new breakouts, direction flips, jumps). - **AI agents and LLM pipelines:** compact stats, a plain-English `insight` and stable status fields on every item. ### Quick start 1. Enter **search terms**. These can be keywords, topic IDs such as `/m/0d6lp`, or Google Trends explore URLs. You can also point **Google Sheet** at a shared sheet, and the Actor reads the terms from its first column. 2. Choose **locations** (`US`, `US-TX`, `GB`…; leave it empty for worldwide), a **time range**, and optionally a **category** or **search type** (web, news, images, YouTube, shopping). 3. Optionally add **Trending Now countries**. 4. Click **Start**. Results appear in the **Output** tab, and CSVs are in the key-value store. #### Input examples ```json { "searchTerms": ["coffee", "tea", "matcha", "cold brew", "kombucha", "yerba mate", "oat milk"], "geos": ["US"], "timeRange": "today 12-m" } ``` Seven terms on one scale, with regions and related queries for each. ```json { "searchTerms": ["solar panels"], "geos": ["US-TX"], "regionLevels": ["DMA", "CITY"], "maxRegions": 10 } ``` Metro- and city-level demand inside Texas. ```json { "trendingNowGeos": ["US", "GB", "IN"], "trendingNowHours": "24", "trendingNowCategories": ["Sports"], "trendingNowSort": "searchVolume", "trendingNowMaxItems": 15 } ``` Daily Trending Now report, with news articles for each trend. ```json { "searchTerms": ["ai agents", "mcp server"], "geos": ["US"], "outputMode": "newOrChanged" } ``` Breakout alerts. Schedule it, and each run returns (and charges) only what changed. ```json { "searchTerms": ["https://trends.google.com/trends/explore?date=today%2012-m&geo=US&q=aeropress,chemex,moka%20pot"] } ``` Paste any Trends explore URL. Its location, time and category are used. ```json { "spreadsheetId": "https://docs.google.com/spreadsheets/d//edit", "geos": ["US"] } ``` Keywords from a Google Sheet shared as "Anyone with the link can view" (first column, header optional). ### Output #### Term report (default dataset, one item per term × location) Headline fields: `avgInterest`, `latestInterest`, `peakInterest` + `peakDate`, `lowInterest`, `changePct` (first vs last quarter of the range), `recentChangePct`, `trendDirection` (rising/falling/stable), `topRegion`, `topRelatedQuery`, `topRisingQuery` + growth, `breakoutQueries`, and a one-sentence `insight`. Detail arrays: `timeline[]`, `regions[]`, `relatedQueriesTop[]`, `relatedQueriesRising[]`. Diagnostics: `scale` (quality and anchor chain), `sections` (status of each part), `errors[]`, `change` (since the last run) and `trendsUrl` (the same query on Google Trends). Real item from a 12-term run on the platform on 2026-10-20 (arrays shortened): ```json { "type": "termReport", "term": "hoka", "geo": "US", "geoName": "United States", "timeRange": "today 12-m", "status": "ok", "sections": { "interestOverTime": "ok", "interestByRegion": "ok", "relatedQueries": "ok", "relatedTopics": "withheld" }, "avgInterest": 12.33, "latestInterest": 8.15, "peakInterest": 25.34, "peakDate": "2026-04-12", "changePct": -8.6, "recentChangePct": -12, "trendDirection": "stable", "granularity": "week", "scale": { "type": "batch", "batchSize": 12, "anchorTerm": "running shoes", "quality": "anchored", "chain": ["scaled via anchor \"running shoes\""], "rankInBatch": 6 }, "topRegion": "Wyoming", "topRelatedQuery": "hoka shoes", "topRisingQuery": "hoka women's transport 2", "topRisingQueryGrowth": "+3,350%", "insight": "Interest in \"hoka\" (United States, past 12 months) is stable (-9% first vs last quarter); peak 25.34 on 2026-04-12, latest 8.15; #6 of 12 compared terms; most popular in Wyoming; top rising query \"hoka women's transport 2\" (+3,350%).", "regions": [{ "level": "REGION", "rank": 1, "geoCode": "US-WY", "geoName": "Wyoming", "value": 100 }, { "level": "REGION", "rank": 2, "geoCode": "US-HI", "geoName": "Hawaii", "value": 33 }], "relatedQueriesTop": [{ "rank": 1, "query": "hoka shoes", "value": 100 }, { "rank": 2, "query": "hoka bondi", "value": 45 }], "relatedQueriesRising": [{ "rank": 1, "query": "hoka women's transport 2", "growthPct": 3350, "isBreakout": false, "formattedValue": "+3,350%", "containsTerm": true }], "timeline": [{ "date": "2025-10-19", "value": 9.5 }, { "date": "2026-10-18", "value": 8.15, "partial": true }], "change": { "status": "new" } } ``` Values are on the shared batch scale: the most popular term in the batch ("sneakers") peaks at 100. Small terms keep 3 significant digits (for example `0.0312`), so they are never flattened to 0. #### Trending Now (dataset `trending`, one item per trending search) ```json { "type": "trendingSearch", "rank": 1, "googleRank": 1, "term": "is kim jong un still alive", "geo": "US", "hoursWindow": 24, "searchVolume": 200000, "searchVolumeLabel": "200K+", "growthPct": 1000, "startedAt": "2026-10-19T18:00:00.000Z", "endedAt": null, "isActive": true, "durationHours": 20.4, "categories": ["Politics"], "relatedQueries": ["kim jong un dead", "did kim jong un die", "kim jong un is he alive"], "newsArticles": [{ "title": "Kim Jong Un: Why do rumours about his death keep coming back?", "url": "https://www.bbc.com/news/articles/cmvg6qv1jdydo", "source": "BBC", "publishedAt": "2026-10-20T11:45:49.000Z", "picture": "https://encrypted-tbn1.gstatic.com/images?q=tbn:…" }], "change": { "status": "new" } } ``` #### Comparison (dataset `comparison`, one item per batch) Every term in the batch is ranked, with `avgInterest`, `shareOfInterestPct`, `vsLeaderPct`, peak, direction and scale quality. Example insight: *"sneakers" leads 12 compared terms in United States (past 12 months); #2 "sandals" has 82% of its interest; last "barefoot shoes" has 3.5%.* #### CSV files and run summary (key-value store) - `TIMELINE.csv` (long format) and `TIMELINE_WIDE.csv` (one column per term, ready for charts) - `REGIONS.csv`, `RELATED_QUERIES.csv`, `TRENDING.csv` and `COMPARISON.csv` - `OUTPUT`: status of each term, totals, charged events, and connection stats (requests, retries, rate limits absorbed, proxy tier used) ### How the shared scale works Google compares at most 5 terms per request and scales each request to its own peak of 100. For more than 5 terms, the Actor puts the most popular term (or your `anchorTerm`) into every group of 4 others. It then rescales each group by the anchor's ratio over the overlapping periods. A term that is too small to measure precisely against the anchor (raw value under 10) is measured again next to a closer-sized term (a "bridge"). Finally, the scale is normalised so the top term peaks at 100. Each term reports `scale.quality`: - `exact`: in the same request as the leader. - `anchored`: scaled through the anchor. - `bridged`: scaled through a closer-sized term. - `approximate`: low precision. - `unscaled`: no overlap with the anchor. To get each term on its own 0–100 scale instead, set `compareTerms: false`. ### Monitoring: what changed since the last run Every term report and trending search carries `change.status` (`new`, `changed` or `unchanged`) and `change.events`. The events are new rising queries, new breakouts, a direction change, a top-region change, and interest jumps or drops beyond `changeThreshold` points. Runs with the same input share a monitor automatically; to pin one, set `monitorKey`. With **Output** set to "New + changed items", unchanged items are neither saved nor charged. **No false alarms from Google's sampling.** Google samples its rising-queries list, so two requests a few minutes apart can return different subsets of 25. A naive "new query since last run" alert therefore fires on almost every term (we measured 12 of 12 terms flagged on an unchanged rerun). This Actor counts a rising query as new only if it has never been seen for that term, contains the term, and is a Breakout or ranks in the top 15. It must also still be there when the list is requested twice more in the same run; those extra requests happen only when there is a candidate, and you aren't charged for them. Rising-query alerts start on the third run; the first two runs build the baseline. Direction, region and interest changes are reported from the second run. The trade-off is deliberate: a query that Google's samples disagree on is treated as noise, so a genuinely new query can show up a run later than on the website. In exchange, alerts don't cry wolf. ### Pricing Pay per result. **There is no start fee, and platform and proxy usage are included.** | Event | Free plan | Starter | Scale | Business and above | |---|---|---|---|---| | Term report (one term × one location × one time range) | $1.50 / 1,000 | $1.20 / 1,000 | $1.00 / 1,000 | $0.75 / 1,000 | | Trending search | $0.40 / 1,000 | $0.30 / 1,000 | $0.25 / 1,000 | $0.25 / 1,000 | | Timeline row in the optional long-format `timeline` dataset (off by default) | $0.02 / 1,000 | $0.02 / 1,000 | $0.02 / 1,000 | $0.02 / 1,000 | | Comparison items, CSV files (including the full timeline), run summary | free | free | free | free | | Terms that fail or are below Google's volume floor | free | free | free | free | Examples on the Free plan: 100 keywords in one country cost **$0.15**. A weekly monitor of 20 keywords costs about **$0.13 a month**. A daily Trending Now feed of 25 trends in each of 3 countries costs about **$0.90 a month**. A term with partial data (for example, regions failed but the timeline and queries arrived) is charged as one report, and its `sections` and `errors` show what is missing. To cap spending, set **Maximum cost per run** in the run options. The Actor stops cleanly at the limit and never saves more than you pay for. ### Use with AI agents (MCP) The Actor runs with limited permissions and pay-per-event pricing without a start fee, so it works with the Apify MCP server and agentic payments. Every field has a title and description in the dataset schema. Each item has a plain-English `insight` and stable `status`/`sections` values, so an agent can tell what is missing and why. A compact agent call is `{"searchTerms": ["topic a", "topic b"], "geos": ["US"], "includeTimeline": false}`, which returns stats without the timeline arrays. ### Limits and honest notes - **Related topics:** Google currently withholds related topics from automated sessions. Every client we tested got empty topic lists, including a real browser, datacenter IPs and residential IPs. The Actor returns topics whenever Google serves them; otherwise it sets `sections.relatedTopics: "withheld"`, at no extra cost. Related **queries** work normally. - **Off-topic rising queries:** Google sometimes adds generic queries (such as "home workout routines") to rising lists for automated clients. Every rising row has `containsTerm`. The headline fields use on-topic rows only, and `risingQueriesFilter: "containingTerm"` removes the rest. - **Sampling:** Google Trends values are sampled and rounded, so they can differ slightly between runs and from the website. Small states such as Wyoming often rank first for common terms. A real browser on the Trends website gets the same ranking (checked against a browser-based scraper on the same day). - **Speed:** heavy runs are paced to stay under Google's rate limits, at roughly 2–6 seconds per term in large batches. A 12-term batch with regions and related queries took 23 seconds. A 23-term batch on a day of heavy rate limiting took 2 minutes, with 15 rate-limit responses absorbed. - **Bad days at Google:** when Google throttles very hard, the run doesn't grind until the platform timeout. It stops starting new requests at a time budget (about 4 minutes plus 30 seconds per term, at most 30 minutes, always ahead of the run timeout) or once a small residential-proxy traffic budget is used, saves everything it already fetched, and marks the rest `status: "error"` with `code: "time_budget"` or `"traffic_budget"`. Those items are not charged. Set **Max run time** (`maxRunSeconds`) to change the time budget. - **Trending Now news:** Google lists up to 3 articles per trend. In our final test, all 75 trends (US, GB, DE) had 3 each. ### FAQ **Why do other Google Trends scrapers fail or return empty results?** Google rate-limits (HTTP 429) aggressively and often answers automated traffic with a captcha page. This Actor paces requests, retries with backoff and fresh sessions, and moves to Apify datacenter and then residential proxies when needed. The proxy cost is included in the price. If Google still blocks a term after all retries, that term comes back as an error item with a hint, and you are not charged for it. **Can I compare more than 5 keywords?** Yes, any number (up to 2,000 per run). See "How the shared scale works". **Why are related topics empty?** Google withholds them from automated sessions (see "Limits"). Related queries are not affected. **Why do my numbers differ slightly from the Google Trends website?** Google samples its data, so two requests minutes apart can differ by a point or two. Batches of more than 5 terms are also rescaled to the batch leader. `trendsUrl` opens the same query on Google Trends. **Is there an official Google Trends API?** Google's Trends API is in limited alpha (by application only). This Actor reads the same public endpoints that the Trends website uses. **Do I need a proxy?** No. The Actor uses Apify Proxy automatically when Google rate-limits it. You can force a proxy group in the advanced settings. **Which time ranges work?** Past hour, 4 hours, day, 7 days, 30 and 90 days, 12 months, 5 years, since 2004, and custom ranges such as `2024-01-01 2024-06-30`. **Is scraping Google Trends legal?** The Actor collects public, aggregated and anonymous statistics. Check the terms that apply to your use. Found a bug or need a field? Open an issue on the **Issues** tab. Issues are answered there. # Actor input Schema ## `searchTerms` (type: `array`): One per line (or comma-separated). Keywords ("cold brew"), Google topic IDs (/m/0d6lp) or Google Trends explore URLs (their own location, time and category are kept). Any number of terms: more than 5 are put on ONE shared 0–100 scale automatically (overlapping anchor groups), so "coffee" and "aeropress" are directly comparable. Leave empty if you only want Trending Now. ## `spreadsheetId` (type: `string`): ID or URL of a Google Sheet shared as "Anyone with the link can view". Terms are read from the first column (a header such as "keyword" is skipped) and added to the search terms. Add #gid=… to the URL to pick a tab. ## `geos` (type: `array`): Empty = Worldwide. ISO country codes (US, GB, DE), subregions (US-CA, GB-ENG), US metro codes (US-CA-807) or country names ("Germany"). Every term is fetched for every location. ## `timeRange` (type: `string`): Same choices as the Google Trends website. For anything else use "Custom time range". ## `customTimeRange` (type: `string`): Overrides Time range. "2024-01-01 2024-06-30" (dates), "2026-10-18T08 2026-10-19T08" (hourly, max 7 days), or "today 3-m" / "now 7-d" style. Dates from 2004-01-01. ## `category` (type: `string`): Google Trends category ID or name: 0 = All, 71 = Food & Drink, 7 = Finance, 18 = Shopping, 5 = Computers & Electronics … (all 1,100+ categories accepted). ## `property` (type: `string`): Which Google search property to measure (as in the Trends website dropdown). ## `searchAs` (type: `string`): Topics include misspellings and translations. The resolved topic ID is reported on each item. ## `compareTerms` (type: `boolean`): On: terms are compared (as when you type several terms into Google Trends) and, beyond 5 terms, stitched onto one scale through shared anchors; each item reports the scale quality. Off: every term is fetched on its own 0–100 scale (best for unrelated terms; enables related topics). ## `anchorTerm` (type: `string`): Term placed in every 5-term group to stitch the scale. Default: the most popular of your terms is found automatically. Set one to compare runs with each other. ## `includeInterestOverTime` (type: `boolean`): Average, latest, peak, low, direction, change % and the full timeline per term. ## `includeTimeline` (type: `boolean`): Off keeps items small (stats only); the full table is always in TIMELINE.csv. ## `includeInterestByRegion` (type: `boolean`): Where each term is most popular. ## `regionLevels` (type: `array`): Pick several to get e.g. states AND metros AND cities in one run. ## `maxRegions` (type: `integer`): 0 = all regions Google returns. ## `includeLowVolumeRegions` (type: `boolean`): Same as the checkbox on the Trends website. ## `includeRelatedQueries` (type: `boolean`): Top and rising related searches with values, growth %, breakouts and links. ## `risingQueriesFilter` (type: `string`): Google currently mixes generic, off-topic queries ("pet care tips") into rising lists served to automated clients. Each row has containsTerm; the headline fields (topRisingQuery, breakoutQueries) always use on-topic rows. ## `includeRelatedTopics` (type: `boolean`): Only available with "one scale" off. Google currently withholds related topics from automated sessions; they are returned when served and the item says "withheld" otherwise (never charged extra). ## `trendingNowGeos` (type: `array`): Country codes for Google's Trending Now page (US, GB, IN …). Each trending search is one item with search volume, growth %, start/end time, categories, related queries and news articles. ## `trendingNowHours` (type: `string`): Same as the Trends website. ## `trendingNowCategories` (type: `array`): Empty = all. Names or IDs: Sports (17), Entertainment (4), Business and Finance (3), Technology (18), Politics (14), Health (7), Food and Drink (5) … ## `trendingNowActiveOnly` (type: `boolean`): Skip trends that have ended. ## `trendingNowMaxItems` (type: `integer`): 0 = all (the US 24-hour list has ~500+). ## `trendingNowSort` (type: `string`): Relevance is the order of the Trends website. ## `includeTrendingNews` (type: `boolean`): Adds headline, source, link and picture where Google provides them. ## `outputMode` (type: `string`): Each term report is compared with the previous run of the same monitor: new on-topic rising/breakout queries (from the 3rd run; Google samples its rising list, so the first two runs build the baseline), direction change, top-region change, jumps/drops. Trending searches are new until seen. Unchanged items are not saved or charged in the filtered modes. ## `monitorKey` (type: `string`): Optional. Default: derived from terms + locations + time + category, so a changed input starts fresh. Set it to keep history while editing the input. ## `changeThreshold` (type: `integer`): Minimum change in latest-vs-peak interest (percentage points) that counts as a jump or drop. ## `includeFailedItems` (type: `boolean`): Terms that fail or have no data get an item with the reason (never charged). ## `outputTimelineRows` (type: `boolean`): Long-format timeline dataset ("timeline") for spreadsheets and BI tools, one row per term per date. $0.02 per 1,000 rows. The same data is free in TIMELINE.csv and in each term report. ## `language` (type: `string`): Interface language for names of regions, categories and topics (en-US, de, ja …). ## `timezoneOffsetMinutes` (type: `integer`): As Google uses it: minutes WEST of UTC (US Central = 300). Affects hourly/daily buckets. ## `maxConcurrency` (type: `integer`): Parallel requests to Google. Higher is faster but triggers more rate limiting. ## `maxRetries` (type: `integer`): Rate-limited requests are retried with backoff, a fresh session and (if needed) a better proxy tier. ## `maxRunSeconds` (type: `integer`): Stop starting new requests after this many seconds and save what was fetched. Leave empty for automatic (about 4 min + 30 s per term, max 30 min). Terms not fetched are marked failed and not charged. ## `proxyConfiguration` (type: `object`): Not needed: the Actor starts without a proxy and automatically escalates to Apify datacenter and then residential proxy if Google rate-limits (proxy cost is included in the price). Choose a proxy here to start on it. ## `autoProxyEscalation` (type: `boolean`): Switch to a better proxy tier after repeated rate limits. ## `debugForce429` (type: `integer`): Testing only: the first N requests return a simulated HTTP 429 so you can see the retry logic work. Leave 0. ## Actor input object example ```json { "searchTerms": [ "coffee", "tea", "matcha" ], "geos": [ "US" ], "timeRange": "today 12-m", "category": "0", "property": "web", "searchAs": "keyword", "compareTerms": true, "includeInterestOverTime": true, "includeTimeline": true, "includeInterestByRegion": true, "regionLevels": [ "auto" ], "maxRegions": 25, "includeLowVolumeRegions": false, "includeRelatedQueries": true, "risingQueriesFilter": "all", "includeRelatedTopics": true, "trendingNowGeos": [ "US" ], "trendingNowHours": "24", "trendingNowActiveOnly": false, "trendingNowMaxItems": 25, "trendingNowSort": "relevance", "includeTrendingNews": true, "outputMode": "all", "changeThreshold": 15, "includeFailedItems": true, "outputTimelineRows": false, "language": "en-US", "timezoneOffsetMinutes": 0, "maxConcurrency": 3, "maxRetries": 7, "proxyConfiguration": { "useApifyProxy": false }, "autoProxyEscalation": true, "debugForce429": 0 } ``` # Actor output Schema ## `termReports` (type: `string`): One item per search term per location: average/latest/peak interest on one shared scale, direction, change %, top region, top and rising related queries, timeline, scale quality, plain-English insight and the change since the last run. ## `risingQueries` (type: `string`): The term reports shown one rising related query per row (growth, breakout, on-topic flag). ## `changes` (type: `string`): What changed per term since the previous run of the same monitor (new rising queries and breakouts, direction or top-region change, interest jumps and drops). ## `trending` (type: `string`): Google Trending Now searches per country: volume, growth %, start/end time, categories, related searches and news articles. ## `comparison` (type: `string`): All terms ranked on the shared scale with share of interest and % of the leader. ## `timelineCsv` (type: `string`): term, location, date, value: every data point of every term. ## `timelineWideCsv` (type: `string`): Spreadsheet-ready: one row per date, one column per term (first location). ## `regionsCsv` (type: `string`): term, level, region code and name, value. ## `relatedCsv` (type: `string`): term, top/rising, rank, query, value, breakout and on-topic flags. ## `summary` (type: `string`): JSON summary: resolved inputs, per-term status, totals, charged events, connection statistics (requests, retries, rate limits absorbed, proxy tier), notes and errors. # 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", "tea", "matcha" ], "geos": [ "US" ], "trendingNowGeos": [ "US" ], "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("chaptersoft/google-trends-reliable").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", "tea", "matcha", ], "geos": ["US"], "trendingNowGeos": ["US"], "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("chaptersoft/google-trends-reliable").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", "tea", "matcha" ], "geos": [ "US" ], "trendingNowGeos": [ "US" ], "proxyConfiguration": { "useApifyProxy": false } }' | apify call chaptersoft/google-trends-reliable --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,chaptersoft/google-trends-reliable" } } } ``` 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/QQo3rf2y9nTakUzdg/builds/PdudL9Qg5QIajPHUN/openapi.json