# Google Trends Scraper ($0.96/1K): Interest & Trending Now (`tsutseisoftware/google-trends-scraper`) Actor

Scrape Google Trends: interest over time, interest by region and city, related queries and topics, comparisons, more than 5 terms on one scale, daily data over years, Trending now per country with news, keyword alerts. Fast, cheap, retries politely. Unofficial.

- **URL**: https://apify.com/tsutseisoftware/google-trends-scraper.md
- **Developed by:** [Tsutsei Software](https://apify.com/tsutseisoftware) (community)
- **Categories:** SEO tools, Automation
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.03 / 1,000 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: Interest, Regions, Trending Now

Scrape **Google Trends** without an API key: interest over time, interest by region (country, region, metro, city), related queries and related topics (top and rising), comparisons of up to 5 terms, **any number of terms on one common scale**, **daily data over years**, and the **Trending now** list of any country with search volume, growth and news. Monitor keywords and trends on a schedule and get alerts in Slack, Discord, Telegram, WhatsApp or a webhook. Export to JSON, CSV or Excel.

This actor is not affiliated with Google. Google Trends values are relative (0-100), not numbers of searches.

### Why use this scraper?

- **Everything Google Trends shows, in one run:** time series, regions with resolution, related queries and topics, all search types (web, images, news, YouTube, Google Shopping), categories, any time range down to the minute, language and time zone.
- **More than Google shows:** more than 5 terms on one scale (calibrated across batches, with an error bound per term), daily data over 12 months, 5 years or since 2004 (stitched windows on one scale), change of interest in percent, Trending now with up to ~450 trends per country.
- **Reliable and polite:** Google's cookie handled, a steady pace (30 requests a minute), a refused request is asked once more after a pause from the same session; a term that cannot be read is **never charged** and the status says which ones. The run fails only when nothing could be read.
- **Cheap:** a term report with all its data for **$0.96 per 1 000** (Gold $0.23), trending searches for $0.76 per 1 000 (Gold $0.03), no extra platform costs.
- **Excel-friendly:** nested JSON for programs, or a flat output with one CSV row per data point.

### What data can you get?

**Term report** (one row per term and location; `rowType: "term"`):

| Field | Example |
|---|---|
| `term`, `geo`, `timeRange`, `category`, `property` | `bitcoin`, `US`, `today 12-m`, `0`, `web` |
| `interestOverTime` | `[{"date": "2026-11-08", "time": "2026-11-08T00:00:00Z", "value": 18, "isPartial": true, "hasData": true}, …]` |
| `averageInterest`, `peakInterest`, `peakDate`, `latestInterest` | `33`, `100`, `2026-02-01`, `22` |
| `recentAverage`, `previousAverage`, `changePercent` | last 4 weeks against the 4 before: `24.5`, `30.25`, `-19` |
| `interestByRegion`, `topRegion`, `regionResolution` | `[{"geoCode": "US-WY", "geoName": "Wyoming", "value": 100, …}]`, `Wyoming`, `region` |
| `comparedRegionShare` | comparisons: each term's share of the searches per region (%) |
| `relatedQueriesTop`, `relatedQueriesRising` | `[{"rank": 1, "query": "bitcoin price", "value": 100}]`, rising with `isBreakout` |
| `relatedTopicsTop`, `relatedTopicsRising` | topics with `topicId`, `title`, `type` |
| `scale`, `comparisonId`, `comparedWith` | `own`, `comparison` or `calibrated` |
| `scaleFactor`, `anchorTerm`, `calibrationErrorPercent` | common scale of more than 5 terms |
| `isStitched`, `stitchWindows`, `stitchErrorPercent` | daily data over long ranges |
| `hasData`, `failedDataTypes`, `isComplete` | `false` = too little search volume |
| `url` | the same chart on trends.google.com |

**Trending search** (`rowType: "trending"`): `title`, `geo`, `rank`, `searchVolume` (`500000`), `searchVolumeText` (`500K+`), `increasePercent` (`1000`), `startedAt`, `endedAt`, `isActive`, `trendCategories` (`Technology`, `Sports`…), `relatedSearches` (the trend breakdown), `newsArticleCount`, `news` (`title`, `url`, `source`, `imageUrl`), `imageUrl`, `url`.

Every row has `id` (stable), `source`, `url` and `scrapedAt`; unknown values are `null`, empty lists `[]`, dates ISO 8601.

### How to use it

1. Enter **Search terms** (one per line), or a Google Sheet / CSV URL, or Google Trends URLs, or countries for **Trending now**.
2. Pick the **Location**, **Time range** and **Data to read**; optionally a comparison mode, category, search type or daily data.
3. Click **Start**. Each term takes about 8 seconds (4 requests at a polite pace); 100 terms take about 15 minutes.
4. Download the results as JSON, CSV or Excel, or use the API. With **Output format: flat**, the Output tab also links CSV files with one row per data point.
5. For monitoring, schedule the run daily with **keyword watch** or **only new trends**, and add a Slack, Discord, Telegram or WhatsApp notification.

### Use cases

#### Compare products or brands on one scale (more than 5)

```json
{
  "searchTerms": ["iphone", "samsung galaxy", "google pixel", "xiaomi", "oneplus", "motorola", "nothing phone"],
  "compareMode": "all",
  "geo": ["US"],
  "timeRange": "today 12-m",
  "dataTypes": ["interestOverTime"]
}
```

#### Daily search interest over 5 years (seasonality, forecasting)

```json
{
  "searchTerms": ["air conditioner"],
  "geo": ["US"],
  "timeRange": "today 5-y",
  "dailyData": true,
  "dataTypes": ["interestOverTime"],
  "outputFormat": "flat"
}
```

#### Where is a topic searched most: cities and metro areas

```json
{
  "searchTerms": ["pickleball"],
  "geo": ["US"],
  "timeRange": "today 12-m",
  "dataTypes": ["interestByRegion"],
  "regionResolution": "DMA"
}
```

#### Trending now in several countries, with news

```json
{
  "trendingCountries": ["US", "GB", "DE"],
  "trendingHours": "24",
  "trendingSortBy": "searchVolume",
  "maxTrendsPerCountry": 25
}
```

#### Daily alert on new trends or keyword jumps, to Slack

```json
{
  "searchTerms": ["your brand", "competitor brand"],
  "geo": ["US"],
  "timeRange": "today 3-m",
  "watchKeywords": true,
  "alertChangePercent": 50,
  "alertOnRisingQueries": "any",
  "slackWebhookUrl": "https://hooks.slack.com/services/..."
}
```

#### YouTube search interest from a Google Trends URL

```json
{
  "startUrls": ["https://trends.google.com/trends/explore?q=minecraft,roblox&geo=DE&date=now%207-d&gprop=youtube"]
}
```

### Input details

#### Terms, comparisons and the scale

Google Trends scales every chart to its own maximum: 100 is the highest point of the chart, 50 half of it, 0 too little data. A term on its own is therefore on its own scale, and two separate reports cannot be compared. **Comparison** decides how terms share a scale:

- **Each term on its own**: one report per term and location.
- **Each line is one comparison**: `coffee, tea, matcha` in one line is one chart of up to 5 terms on one scale (like on the website).
- **All terms on one common scale**: any number of terms. Google compares at most 5 at once, so the actor reads batches of 5 and links them with an *anchor* term (see below).
- **Each term compared across the locations**: one chart per term with up to 5 locations (e.g. pizza in US, DE and IT).

A topic is given by its Google ID (`/m/02vqfm` is the topic "Coffee"; take it from the `q=` of a Google Trends URL after choosing a topic).

#### More than 5 terms on one scale: how it works and how exact it is

The first batch has 5 terms. Every next batch has 4 new terms and one **anchor** term from an earlier batch. The anchor's values in both batches give the factor between them (ratio of the sums over the same points), so every batch is brought onto the first batch's scale; at the end everything is rescaled so that the highest point of all terms is 100. The anchor is the least popular term of the first batch with a peak of at least 20 (you can choose it with **Anchor term**); when a new term pushes the anchor below 10 in a batch, that batch's most popular term carries the scale on.

Google rounds values to whole numbers, so the factor is not exact. `calibrationErrorPercent` is an upper bound of the factor's error from this rounding (typically 1-4 %; it adds up along a chain of anchors). On top of it, a term whose own values are tiny next to the batch's biggest term (peaks of 1-3) has a large relative error of its own: put terms of very different popularity in different runs or let them share batches with similar terms. Extra charge "Calibrated term" per term.

#### Daily data over long periods: how it works and how exact it is

Google gives daily points only for ranges up to 270 days (weekly up to 5 years, monthly beyond). With **Daily data over long periods** the actor reads the range in equal windows of at most 270 days and scales each window so that its weekly (or monthly) averages match Google's weekly (monthly) series of the whole range, which is on one scale. Each window is anchored to that series directly, so errors do not build up from window to window; then the whole series is rescaled to a maximum of 100. `stitchErrorPercent` is an upper bound of the windows' factor error from rounding (about 1-2 % for popular terms; larger for terms with low weekly values). Each window costs 2 requests and the "Daily data window" event; 5 years are 7 windows. Comparisons (up to 5 terms) are stitched with one factor for all terms, so their ratios stay as Google measured them.

#### Regions

`interestByRegion` lists the regions sorted by value (100 = the region with the highest **share** of searches, not the most searches). **Region resolution**: countries (worldwide), regions/states, metro areas (US only, `DMA`) or cities (with coordinates). **Include low search volume regions** adds regions without enough data (`hasData: false`).

#### Trending now

The list of the "Trending now" page of a country (all trends of the last 4, 24, 48 hours or 7 days, often 100-450): search volume, growth, start and end time, categories, related searches, and news articles from Google's trending feed for the newest trends. Filter by category or active trends, sort by volume, growth or recency, limit per country.

#### Monitoring and alerts

- **Only new trends**: a scheduled run saves only trends not reported before (state kept under **Monitoring: key**).
- **Keyword watch**: a term is saved only when its interest changed by at least **alert on a change of** % (last N points against the N before, inside one chart, so on one scale) or when a rising related query appears that earlier runs did not see (`alertReasons`, `newRisingQueries`). The first run saves every term as the baseline. A checked term without an alert is not saved and costs only the small "Monitoring check" fee.
- **Notifications** to Slack, Discord, Telegram, WhatsApp or any webhook after the run.

### How much does it cost to scrape Google Trends?

Pay per event (the **Pricing** tab always shows the current prices):

| Event | Price | When |
|---|---|---|
| Result | $0.76 / 1 000 (Bronze $0.66, Silver $0.21, Gold and up $0.03) | every saved row: a term report or a trending search |
| Term report | + $0.20 / 1 000 | every saved term report (with all its data types); a term report costs $0.96 / 1 000 (Bronze $0.86, Silver $0.41, Gold and up $0.23) |
| Actor start | $0.003 | once per run |
| Calibrated term | + $0.01 / 1 000 | a term on the common scale of more than 5 terms |
| Daily data window | $0.15 / 1 000 windows | each 270-day window of a stitched daily series (5 years = 7 windows) |
| Monitoring check | $0.30 / 1 000 | keyword watch: a term checked without an alert; only new trends: each country list read |
| Extra page | $0.10 / 1 000 | only when a run would cost more than it charged (Google answering very slowly); a normal run pays nothing here |
| Notification | $0.001 | once per run that sent its notification |

Examples: 1 000 term reports (interest over time, regions and related queries) cost **$0.96** (Gold $0.23); 1 000 trending searches **$0.76** (Gold $0.03); 100 terms with daily data over 5 years about **$0.20** (100 × $0.00096 + 700 windows × $0.00015 + start). Terms that could not be read are not charged, and there are no extra platform costs (compute, traffic) on top. The free $5 of monthly Apify credit is enough for about 5 200 term reports. You can set a maximum cost per run; the actor stops when it is reached.

### Input example

```json
{
  "searchTerms": ["bitcoin", "ethereum"],
  "geo": ["US"],
  "timeRange": "today 12-m",
  "dataTypes": ["interestOverTime", "interestByRegion", "relatedQueries"],
  "maxItems": 10
}
```

### Output example

```json
{
  "id": "trends:bitcoin:us:today_12-m:0:web",
  "rowType": "term",
  "source": "google-trends",
  "term": "bitcoin",
  "termType": "searchTerm",
  "geo": "US",
  "timeRange": "today 12-m",
  "startDate": "2025-11-12",
  "endDate": "2026-11-12",
  "resolution": "week",
  "category": 0,
  "categoryName": "All categories",
  "property": "web",
  "scale": "own",
  "hasData": true,
  "interestOverTime": [
    {"date": "2025-11-09", "time": "2025-11-09T00:00:00Z", "value": 40, "isPartial": false, "hasData": true},
    {"date": "2026-11-08", "time": "2026-11-08T00:00:00Z", "value": 18, "isPartial": true, "hasData": true}
  ],
  "interestOverTimePoints": 53,
  "averageInterest": 32.66,
  "peakInterest": 100,
  "peakDate": "2026-02-01",
  "latestInterest": 17,
  "latestDate": "2026-11-01",
  "recentAverage": 16.0,
  "previousAverage": 18.75,
  "changePercent": -14.7,
  "interestByRegion": [{"geoCode": "US-WY", "geoName": "Wyoming", "value": 100, "hasData": true, "latitude": null, "longitude": null}],
  "regionResolution": "region",
  "topRegion": "Wyoming",
  "relatedQueriesTop": [{"rank": 1, "query": "bitcoin price", "value": 100, "formattedValue": "100", "url": "https://trends.google.com/trends/explore?q=bitcoin+price&date=today+12-m&geo=US"}],
  "relatedQueriesRising": [{"rank": 1, "query": "spcx stock", "value": 17350, "formattedValue": "Breakout", "isBreakout": true, "url": "https://trends.google.com/trends/explore?q=spcx+stock&date=today+12-m&geo=US"}],
  "failedDataTypes": [],
  "isComplete": true,
  "url": "https://trends.google.com/trends/explore?q=bitcoin&date=today%2012-m&geo=US",
  "scrapedAt": "2026-11-12T13:30:00Z"
}
```

### Limitations

- **Values are relative**, not search counts: 0-100 within one chart (or within the common scale). The trending `searchVolume` is Google's rounded lower bound ("500K+").
- **Related topics**: Google currently returns empty related topics to automated requests (also for single terms); the actor asks for them when you select them and fills them if Google returns them. For comparisons Google has no related topics at all.
- **Google samples its data**: two runs of the same chart can differ by a few points.
- **Speed**: about 30 requests a minute (4 per term), so large lists take time (1 000 terms about 2 hours). Google refuses fast clients; the pace is what keeps runs reliable.
- **Refusals**: Google sometimes answers "too many requests" or shows its "unusual traffic" page. The actor waits a minute and asks once more from the same session; it never solves CAPTCHAs and never switches IP to get around a refusal. A term refused twice is reported in the status, not charged, and the run stops after 2 refused terms in a row (after the first one when nothing could be read yet; try again later or with Apify Proxy).
- **News of trends** come from Google's trending feed, which covers the newest trends of the country (about 10), so many trends have `news: []` but still `newsArticleCount`.
- The common scale and daily stitching are estimates with the error bounds above; daily stitching is not combined with the common scale of more than 5 terms (those get weekly data).

### For AI agents and API users

Each row is flat at the top level with stable `id`s; nested lists hold the data points. For tables use `outputFormat: "flat"` and read `interest-over-time.csv`, `interest-by-region.csv` and `related-queries.csv` from the run's key-value store (linked in the Output tab and listed in `SUMMARY`). `SUMMARY` also lists every term with its status (`ok`, `noData`, `refused`, `failed`).

### Troubleshooting

- **"N terms could not be read (Google refused the requests)"**: Google limited the requests from the run's IP. Run those terms again later; with many terms, set **Proxy configuration** to Apify Proxy (each batch of 20 reports then uses its own IP).
- **`hasData: false`**: the term has too little search volume for Google Trends in that location and time; try a longer range, a bigger location or a broader term.
- **A location code is not accepted**: use ISO codes (US, GB, DE), subregions (US-CA, GB-ENG) or US metros (US-NY-501).
- **`failedDataTypes` not empty**: some data of the report was refused; the rest is there (and the report is charged once).

### Integrations

Connect the results to the tools you already use with the built-in integrations of Apify (the **Integrations** tab of the actor or of a saved task), with no code:

- **Google Sheets or Google Drive:** the results of every run in a spreadsheet or a file.
- **Zapier, Make and n8n:** start a workflow when a run finishes, or start the actor from one.
- **Slack or e-mail:** a message from Apify when a run finishes or fails.
- **Webhooks:** your own address gets the details of each run.
- **API and MCP:** run the actor from your code, or let an AI assistant run it through the Apify MCP server.

The results also download as Excel, CSV, JSON or XML from the **Output** tab.

### Privacy and error reports

When a run fails, the actor sends its developer a short error report: the error, the run ID and your input with secrets left out (tokens, webhooks, e-mails and similar values are hidden). Your results are never sent. Reports are deleted after at most 120 hours (5 days). To send nothing, turn off **Send error reports** (`sendErrorReports: false`). Questions about your data: open an issue in the **Issues** tab of this actor.

### More news and trend scrapers

The same clean output and alerts for another news or trend source:

- [Google News Scraper](https://apify.com/tsutseisoftware/google-news-scraper): articles for any search, topic or country with the real publisher URL, full text and new article alerts
- [Telegram Channel Scraper](https://apify.com/tsutseisoftware/telegram-channel-scraper): posts of public Telegram channels with views, reactions and media, any date range, new, edited and deleted post alerts

### WhatsApp notifications: setup

The actor sends the message from your own WhatsApp business number through the WhatsApp Cloud API of your Meta business account. You need a Meta business account; the actor uses only the values you enter in the **Notifications** section (the token and the numbers are stored encrypted and never written to the log).

1. **Create an app.** In Meta for Developers open **My Apps → Create app** and choose the use case **Connect with customers through WhatsApp**.
2. **Get a sending number.** In the app open **WhatsApp → API Setup**. You can start with the test number Meta gives you and add your own business number there later. Copy the **Phone number ID** (not the number itself) into **WhatsApp phone number ID**.
3. **Confirm the recipients (test number only).** A test number sends only to numbers on its list: in **API Setup**, under **To**, add each recipient's number and confirm it with the code WhatsApp sends to it.
4. **Create a permanent access token.** The token shown in API Setup expires within hours. In **Business settings → System users** add a system user, use **Assign assets** to give it your app (and your WhatsApp account), then **Generate token** for the app with the permissions `whatsapp_business_messaging` and `whatsapp_business_management` and the expiry you want. Paste it into **WhatsApp access token**.
5. **Create a message template (recommended).** In **WhatsApp Manager → Message templates → Create template** choose the category **Utility**, a name (e.g. `apify_results`) and a language, and write a body with two variables, for example: `New results of your Apify task: {{1}} Open the dataset: {{2}} (sent automatically after each run).` Meta does not accept a body that starts or ends with a variable and asks for sample values (e.g. `3 new jobs` and a dataset link); keep the text factual, a promotional text is moved to the Marketing category. Approval can take up to 24 hours. Enter the name in **WhatsApp template name** and its language code (e.g. `en_US`, `cs`, `pl`, `de`, as WhatsApp Manager shows it) in **WhatsApp template language**.
6. **Enter the recipients.** **WhatsApp recipient number** takes up to 5 numbers with the country code (e.g. `+420601234567`), separated by commas or new lines. Each number gets its own message.

**What the message contains.** With a template: `{{1}}` is the run summary with the first results on one line (title, company or price, place; never descriptions or contacts) and `{{2}}` the link to the dataset. A template with only `{{1}}` works too, it then gets the link at the end. Without a template the actor sends a text message with one link per result, like in Slack or Telegram.

**Without a template** WhatsApp delivers the message only when the recipient wrote to your business number in the last 24 hours (the customer service window), so a daily or hourly schedule needs a template. The run log says so once per run.

**What it costs.** Meta bills your business account, not this actor: per delivered message, by the message category (a template of the Utility category, or a service message for text in the 24-hour window, with a monthly free allowance per business number) and by the recipient's country. The current rates are in Meta's pricing of the WhatsApp Business Platform. The actor's own notification charge (see the **Pricing** tab) is once per run that delivered its notification, whatever the number of channels and recipients.

**Checked at the start.** When the run starts, the actor checks the token, the phone number ID and, when the token shows its WhatsApp account, the template (name, language, approval), without sending anything. Settings that can't work stop the run with a message that says what to fix, before anything is read from the website.

**When nothing arrives**, the run log names the WhatsApp error and what to do: a template that does not exist in that language or is not approved yet, a template with another number of variables, a recipient missing from the test number's list, an expired token, or the 24-hour window. A failed notification never fails the run and is not charged. Meta can accept a message and still not deliver it later (for example when the recipient's phone is not on WhatsApp); such a run counts as notified.

### FAQ

#### Is it legal to scrape Google Trends?

The actor reads only aggregated, anonymous statistics that Google Trends shows to every visitor without logging in, at a polite pace, and it never solves CAPTCHAs or other access checks. Google's terms of service may restrict automated access and reuse of the data, so you are responsible for how you use it; if in doubt, consult a lawyer. This actor is not affiliated with, endorsed by or connected to Google.

#### How is it different from Apify's own Google Trends Scraper?

The official actor costs $6 per 1 000 results ($3 on Gold); this one costs $0.96 per 1 000 term reports ($0.23 on Gold) and $0.76 per 1 000 trending searches ($0.03 on Gold). On top of the time series, regions, related queries and topics, categories, custom ranges, start URLs and Google Sheet input that both have, this actor adds: more than 5 terms on one common scale, daily data over long ranges, the Trending now list with volume, growth and news, all search types (images, news, YouTube, Shopping), region resolution down to cities, multiple locations per term, flat CSV output, keyword watch with alerts, new-trend monitoring and notifications, and a clear status of what could not be read (not charged).

#### Why are the numbers not search volumes?

Google Trends publishes only relative interest (0-100). The only absolute numbers are the rounded search volumes of trending searches ("200K+").

#### Can I compare two separate reports?

Only reports on the same scale: the terms of one comparison (`comparisonId`) or of one common scale (`scale: "calibrated"`). Each term on its own has its own 100.

#### Do I need a proxy?

Usually not: Google Trends answers at the actor's pace without one. If a run reports refused terms, try again later or use Apify Proxy.

#### Can I use it via API, Make, Zapier or n8n?

Yes, like any Apify actor: run it through the Apify API or an integration, schedule it, and read the dataset in JSON, CSV or Excel. Notifications can also post to any webhook.

### Your feedback

Missing a field or an option? Every run's log ends with a link where you can tell us. Also known as a Google Trends API, Google Trends downloader, Google Trends CSV export or trending searches scraper.

# Changelog

This Actor's version history is a separate document: https://apify.com/tsutseisoftware/google-trends-scraper/changelog.md

# Actor input Schema

## `searchTerms` (type: `array`):

One search term or topic per line (a topic is its Google ID, e.g. /m/02vqfm for the topic "Coffee"). Terms separated by commas in one line ("coffee, tea, matcha") are compared on one scale with the comparison mode "Each line is one comparison". Each term in each location is one report (one result).

## `compareMode` (type: `string`):

How the terms are put on Google's 0-100 scale. Google compares at most 5 terms in one chart; "All terms on one common scale" goes beyond that by chaining an anchor term across batches (see the README for the method and its error; extra charge "Calibrated term").

## `anchorTerm` (type: `string`):

Optional, for "All terms on one common scale": the term that links the batches. Empty = picked automatically (the least popular term of the first batch whose peak is at least 20).

## `termsListUrl` (type: `string`):

Optional: a Google Sheet shared with "Anyone with the link", or a direct link to a CSV or text file. The first column holds the terms (a header row such as "keyword" is skipped); a row with several cells is one comparison line. Added to "Search terms".

## `startUrls` (type: `array`):

Optional: explore URLs (https://trends.google.com/trends/explore?q=bitcoin,ethereum\&geo=US\&date=today%205-y) are read with their terms, location, time range, category and search type; "Trending now" URLs (https://trends.google.com/trending?geo=US\&hours=24) give the trending list of that country.

## `trendingCountries` (type: `array`):

Optional: read the "Trending now" list of these countries (country codes such as US, GB, DE, CZ). Every trending search is one result: search volume, growth, start time, related searches, categories and news articles.

## `maxItems` (type: `integer`):

Maximum number of results saved in the run (term reports and trending searches). You pay per result. 0 = no limit.

## `timeRange` (type: `string`):

The period of the charts. Google decides the step of the points by the length: per minute up to 4 hours, hourly up to 7 days, daily up to 270 days, weekly up to 5 years, monthly beyond.

## `customTimeRange` (type: `string`):

With "Custom": two dates "2024-01-01 2024-12-31" (from 2004-01-01) or two hours "2026-11-01T00 2026-11-07T23" (at most 7 days, hourly or finer).

## `geo` (type: `array`):

Country (US, DE, CZ), subregion (US-CA, GB-ENG, DE-BY) or US metro (US-NY-501) codes. Empty = worldwide. Several locations: each term is read for each of them (or compared across them with the comparison "Each term compared across the locations").

## `category` (type: `string`):

Limit the searches to a Google Trends category (e.g. "Shopping" for product searches).

## `categoryId` (type: `integer`):

Optional: any category number of Google Trends (the "cat" in an explore URL, e.g. 1227 for "Sports Coaching & Training"); overrides "Category". 0 = use "Category".

## `searchType` (type: `string`):

Which Google search the interest comes from.

## `language` (type: `string`):

Language of names in the results (regions, topics), e.g. en-US, de, cs, pt-BR.

## `timezoneOffsetMinutes` (type: `integer`):

Offset of your time zone from UTC in minutes (UTC+1 = 60, UTC-5 = -300). Days and hours of the charts start in this time zone; dates in the results carry the offset. 0 = UTC.

## `dataTypes` (type: `array`):

What each report contains. Each kind of data is one request per term, so fewer kinds make the run faster; the price per report is the same. Related topics: Google currently returns none to automated requests (the field stays empty, see the README), and for comparisons it has none at all.

## `regionResolution` (type: `string`):

Level of "Interest by region".

## `includeLowSearchVolume` (type: `boolean`):

Also list regions with too little data (value 0, hasData false), like the checkbox on the website.

## `dailyData` (type: `boolean`):

For ranges longer than 270 days (12 months, 5 years, custom dates): read the range in 270-day windows of daily data and put them on one scale (anchored to Google's weekly series of the whole range; see the README). Extra charge "Daily data window" for every window; 2 requests per window.

## `outputFormat` (type: `string`):

"Flat" is for Excel and CSV: the dataset gets one summary row per term (no lists) and the key-value store gets interest-over-time.csv, interest-by-region.csv, related-queries.csv and related-topics.csv with one row per data point (links in the Output tab). No extra charge.

## `trendingHours` (type: `string`):

How far back the trending searches go.

## `trendingCategory` (type: `string`):

Only trends of this category.

## `trendingActiveOnly` (type: `boolean`):

Skip trends that have already ended.

## `trendingSortBy` (type: `string`):

Order of the trends (and which ones stay with a limit per country).

## `maxTrendsPerCountry` (type: `integer`):

Keep at most this many trends of each country. 0 = all of them (often 100-450).

## `includeTrendingNews` (type: `boolean`):

Add the news articles Google shows for the trends (from Google's trending feed, which covers the newest trends of the country; one more request per country, no extra charge).

## `onlyNewTrends` (type: `boolean`):

Trending now: save only trends not reported by an earlier run with the same Monitoring key (a trend not seen for 3 days counts as new again). Every country list read costs the small "Monitoring check" fee (see Pricing).

## `watchKeywords` (type: `boolean`):

Search terms: save a term only when it has an alert: its interest jumped (see "alert on a change of") or it has a rising related query that earlier runs did not see. The first run saves every term as the baseline. A term checked without an alert is not saved and costs the small "Monitoring check" fee.

## `alertChangePercent` (type: `integer`):

Alert when the average of the last N points differs from the N points before by at least this many percent (up or down). 0 = no alert on changes.

## `alertWindowPoints` (type: `integer`):

N of the comparison. 0 = automatic: 7 days, 24 hours, 4 weeks or 3 months by the time range.

## `alertOnRisingQueries` (type: `string`):

Alert when a related query appears among the rising ones that earlier runs did not see.

## `monitoringKey` (type: `string`):

Name of the saved state. Use a different key for each watched list. Empty = "default". The value is stored encrypted.

## `slackWebhookUrl` (type: `string`):

Incoming webhook of your Slack channel (https://hooks.slack.com/services/...). Stored encrypted.

## `discordWebhookUrl` (type: `string`):

Webhook of your Discord channel (https://discord.com/api/webhooks/...). In Discord: channel settings → Integrations → Webhooks → Copy Webhook URL. Stored encrypted.

## `telegramBotToken` (type: `string`):

Token of your Telegram bot (from @BotFather). Used with "Telegram chat ID". Stored encrypted.

## `telegramChatId` (type: `string`):

Chat, group or channel ID the bot writes to (e.g. -1001234567890).

## `webhookUrl` (type: `string`):

Any HTTPS URL (Zapier, Make, n8n, your server): gets a POST with JSON {title, summary, totalSaved, runUrl, datasetUrl, items}.

## `whatsappAccessToken` (type: `string`):

Access token of the WhatsApp Cloud API of your Meta business account, used with "WhatsApp phone number ID" and "WhatsApp recipient number" (step by step in the README, section "WhatsApp notifications: setup"). For scheduled runs use a permanent token of a system user: Business settings → System users → Generate token, with the permissions whatsapp_business_messaging and whatsapp_business_management; the token of WhatsApp → API Setup expires within hours. Stored encrypted.

## `whatsappPhoneNumberId` (type: `string`):

ID of your WhatsApp business number that sends the message (not the number itself), e.g. 106540352242922. In your Meta app: WhatsApp → API Setup → Phone number ID.

## `whatsappTo` (type: `string`):

Phone number that gets the message, in international format with the country code (e.g. +420601234567); up to 5 numbers separated by commas or new lines, each gets its own message and the notification is charged once per run. A test number of Meta sends only to numbers you added and confirmed under API Setup → To. Stored encrypted.

## `whatsappTemplateName` (type: `string`):

Name of your approved message template (WhatsApp Manager → Message templates, e.g. apify_results), recommended: WhatsApp delivers a template message at any time. Its body gets the run summary with the first results in {{1}} and the dataset link in {{2}} (a template with only {{1}} gets both in {{1}}). Empty: a plain text message, which WhatsApp delivers only when the recipient wrote to your business number in the last 24 hours, so a scheduled run usually needs a template. Meta charges your business account for template messages (step by step in the README, section "WhatsApp notifications: setup").

## `whatsappTemplateLanguage` (type: `string`):

Language code of the template exactly as WhatsApp Manager → Message templates shows it next to the template, e.g. en_US, en_GB, cs, sk, pl or de. Used only with "WhatsApp template name".

## `notificationLimit` (type: `integer`):

How many results are listed in one notification (the rest as "…and N more").

## `notifyOnlyChanges` (type: `boolean`):

Send nothing when the run saved nothing (e.g. a monitoring run without new trends or alerts).

## `proxyConfiguration` (type: `object`):

No proxy by default: Google Trends answers datacenter IPs at a polite pace. With Apify Proxy each batch of 20 reports uses its own IP (never a new IP to repeat a refused request).

## `sendErrorReports` (type: `boolean`):

When a run fails, send the developer a short error report: the error and your input with secrets left out (tokens, webhooks and e-mails are hidden). Your results are never sent. Reports are deleted after at most 120 hours. Turn off to send nothing.

## Actor input object example

```json
{
  "searchTerms": [
    "bitcoin",
    "ethereum"
  ],
  "compareMode": "none",
  "maxItems": 10,
  "timeRange": "today 12-m",
  "geo": [
    "US"
  ],
  "category": "0",
  "searchType": "web",
  "language": "en-US",
  "timezoneOffsetMinutes": 0,
  "dataTypes": [
    "interestOverTime",
    "interestByRegion",
    "relatedQueries"
  ],
  "regionResolution": "auto",
  "includeLowSearchVolume": false,
  "dailyData": false,
  "outputFormat": "nested",
  "trendingHours": "24",
  "trendingCategory": "0",
  "trendingActiveOnly": false,
  "trendingSortBy": "relevance",
  "maxTrendsPerCountry": 0,
  "includeTrendingNews": true,
  "onlyNewTrends": false,
  "watchKeywords": false,
  "alertChangePercent": 50,
  "alertWindowPoints": 0,
  "alertOnRisingQueries": "any",
  "whatsappTemplateLanguage": "en_US",
  "notificationLimit": 10,
  "notifyOnlyChanges": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "sendErrorReports": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `interestOverTimeCsv` (type: `string`):

No description

## `interestByRegionCsv` (type: `string`):

No description

## `relatedQueriesCsv` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchTerms": [
        "bitcoin",
        "ethereum"
    ],
    "maxItems": 10,
    "timeRange": "today 12-m",
    "geo": [
        "US"
    ],
    "dataTypes": [
        "interestOverTime",
        "interestByRegion",
        "relatedQueries"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("tsutseisoftware/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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchTerms": [
        "bitcoin",
        "ethereum",
    ],
    "maxItems": 10,
    "timeRange": "today 12-m",
    "geo": ["US"],
    "dataTypes": [
        "interestOverTime",
        "interestByRegion",
        "relatedQueries",
    ],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("tsutseisoftware/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": [
    "bitcoin",
    "ethereum"
  ],
  "maxItems": 10,
  "timeRange": "today 12-m",
  "geo": [
    "US"
  ],
  "dataTypes": [
    "interestOverTime",
    "interestByRegion",
    "relatedQueries"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call tsutseisoftware/google-trends-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tsutseisoftware/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 <APIFY_API_TOKEN>` 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/i4PamQ8Dw39vTcbue/builds/wMBngFKSFbheRrq3I/openapi.json
