# Google Trends API: Trend Data and Breakout Alerts (`steady-scrape/google-trends-api`) Actor

Google Trends data for any search term or a comparison of up to 5: interest over time, interest by country or sub-region, top and rising related queries and topics, with breakout detection and a scheduled trend-change monitor. API-backed, no blocked runs.

- **URL**: https://apify.com/steady-scrape/google-trends-api.md
- **Developed by:** [SteadyScrape](https://apify.com/steady-scrape) (community)
- **Categories:** SEO tools, Marketing, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 term trend (standard)s

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 Over Time, Regions, Related Queries

Get Google Trends data for any search term, or compare up to **5 terms** on the same scale. One clean row per term with **interest over time, interest by country or region, top and rising related queries and topics**, plus a trend summary and breakout detection. Put it on a schedule and it tells you when a trend changes.

- 📊 **Interest over time**: the full 0–100 series for any preset (past hour to all time since 2004) or your own date range, with average, latest, peak, momentum and a simple `rising` / `falling` / `stable` label
- 🗺️ **Interest by region**: countries worldwide, or states and regions inside a country
- 🔎 **Related queries and topics**: top and rising lists, with **Breakout** (+5000%) items pulled out for you
- 🔔 **Trend-change monitor**: schedule it daily or weekly and get alerts when momentum moves past your threshold, a new breakout shows up, or the trend direction flips
- ⚡ **Two speeds**: **Standard** is cheapest and usually ready in 1–2 minutes. **Live** returns in seconds for a higher price
- ✅ **Reliable**: data comes from a licensed Google Trends API, not from scraping the Trends website, so there are no captchas, 429 errors or timed-out runs
- 💸 **Fair billing**: terms with no data, invalid lines and errors are free

### Quick start

```json
{
  "searchTerms": ["web scraping", "standing desk"]
}
```

Compare terms on the same 0–100 scale (comma-separated, up to 5 per line):

```json
{
  "searchTerms": ["chatgpt, gemini, claude"],
  "region": "US",
  "timeRange": "past_90_days"
}
```

Fast answer for one term:

```json
{
  "searchTerms": ["iphone 17"],
  "dataMode": "live",
  "includeRegions": false
}
```

Weekly monitor (schedule this input in Apify):

```json
{
  "searchTerms": ["standing desk", "walking pad"],
  "region": "US",
  "monitor": true,
  "monitorName": "office-products",
  "alertThresholdPct": 25
}
```

### Output

One row per search term (views: **Overview**, **Related queries & topics**, **Monitor**):

| Field | Example | Notes |
|---|---|---|
| `searchTerm` | `gemini` | |
| `comparedWith` | `["chatgpt", "claude"]` | Other terms on the same line. Values share one scale |
| `status` | `ok` | `ok`, `no_data`, `error`, `skipped`. Only `ok` rows are charged |
| `averageInterest` / `latestInterest` / `peakInterest` | `44.6` / `41` / `100` | 0–100. The last, still-incomplete period is left out of these |
| `peakDate` | `2026-04-12` | |
| `recentAverage` / `previousAverage` / `momentumPct` | `48` / `44` / `8.8` | Latest sixth of the range vs the sixth before it |
| `trend` | `stable` | `rising` (≥ +15%), `falling` (≤ −15%) or `stable` |
| `interestOverTime` | `[{"date":"2026-10-18","dateTo":"2026-10-24","value":41,"partial":false}]` | `partial: true` marks the current, incomplete period |
| `interestByRegion` / `topRegions` | `[{"geoId":"US-CA","geoName":"California","value":100}]` | Regions with no data are left out |
| `relatedQueriesTop` / `relatedQueriesRising` | `[{"query":"claude code","value":4850,"isBreakout":false,"possibleNoise":false}]` | Rising values are % growth |
| `relatedTopicsTop` / `relatedTopicsRising` | `[{"topicId":"/g/…","title":"Claude Code","type":"Topic","value":119100}]` | |
| `breakoutQueries` / `breakoutTopics` / `hasBreakout` | `["claude cowork"]` | Rising items at +5000% or more, without items flagged as possible noise |
| `googleTrendsUrl` | | Opens the same chart on Google Trends |
| `monitor` | `{"alert":true,"alertReasons":["New breakout: …"],…}` | Only in monitor mode |

The `OUTPUT` record has the run summary: totals, alerts, charges and anything skipped.

Export to CSV, Excel or JSON, or connect through the API, Make, n8n, Zapier or Google Sheets.

### Input options

| Option | Default | What it does |
|---|---|---|
| `searchTerms` | | One term per line. Put up to 5 comma-separated terms on a line to compare them |
| `dataMode` | `standard` | `standard`: cheapest, usually 1–2 minutes (can take longer at busy times). `live`: seconds, higher price |
| `timeRange` | `past_12_months` | `past_hour` … `past_5_years`, `all_time` |
| `startDate` / `endDate` | | Custom range (YYYY-MM-DD). Overrides `timeRange` |
| `region` | worldwide | Country or region code or name: `US`, `US-CA`, `Germany`, `uk` |
| `searchType` | `web` | `web`, `news`, `youtube`, `images`, `shopping` |
| `category` | all | Google Trends category, by name or number (`Shopping`, `71`) |
| `includeRegions` / `includeRelated` | `true` / `true` | Turn off what you don't need |
| `monitor` / `monitorName` / `alertThresholdPct` | `false` / `default` / `30` | Trend-change monitor. Use different names for different watchlists |

### Pricing (pay per event)

| Event | Price | When |
|---|---|---|
| Run start | $0.005 | Once per run, only if at least one term returns data |
| Term trend, Standard | $0.006 / term | Each term with data |
| Term trend, Live | $0.02 / term | Each term with data |

A term in a comparison counts as one term. Set **Max cost per run** in the run options. The Actor only fetches what fits in that limit and never charges more. Platform usage is included.

### Good to know

- Google Trends values are **relative** (0–100), scaled to the highest point of the chart. In a comparison all terms share one scale. Values from separate runs or lines can't be compared directly.
- Google samples its data, so numbers can move a little between runs, especially for small terms and short ranges.
- Very small terms often have no data. You get a free `no_data` row for those.
- Rising lists sometimes contain unrelated, huge spikes that come from Google's own data. The Actor flags them as `possibleNoise` (unrelated to your term and not in the top list) and leaves them out of breakouts and alerts. They stay in the lists so you can judge for yourself.
- Related queries and topics are per term. For comparisons the Actor fetches them separately for each term.
- In monitor mode the first run saves a baseline. It already alerts on breakouts and big momentum, and later runs also alert on new breakouts and trend flips.

### FAQ

**Do I need a Google account or API key?** No.

**Why not scrape trends.google.com?** Google rate-limits Trends scraping hard, so scrapers hit 429 errors and time out. This Actor uses a licensed Google Trends data API instead.

**Standard or Live?** Standard for batches, dashboards and schedules. Live when you need the answer right now.

**Something wrong?** Open an issue on the Issues tab. SteadyScrape (steady-scrape) answers there.

### More tools from SteadyScrape (steady-scrape)

- [Keyword Search Volume](https://apify.com/steady-scrape/keyword-search-volume): Google search volume, CPC, competition and a 12-month trend for up to 10,000 keywords per run.
- [Bulk Domain Rank & Traffic Checker](https://apify.com/steady-scrape/domain-seo-metrics): domain rank, backlinks, spam score and estimated traffic for up to 10,000 domains.

Built and maintained by **SteadyScrape (steady-scrape)**. Not affiliated with Google.

### Acceptable use

You may not use results from this service to build or operate a search engine, or any product or service that competes with or harms the business of search engine providers.

— SteadyScrape

# Actor input Schema

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

One search term per line. To compare up to 5 terms on the same 0-100 scale (like the Google Trends compare view), put them on one line separated by commas, e.g. <code>iphone, samsung galaxy, google pixel</code>. You pay per term, so a 3-term comparison is 3 terms.

## `dataMode` (type: `string`):

<b>Standard</b> is the cheaper option: results come from the data provider's queue, usually within 1-2 minutes (rarely up to 45). <b>Live</b> returns results in seconds and costs more per term. Both return the same data.

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

Preset time range. Ignored when you set a start or end date below.

## `startDate` (type: `string`):

Optional custom range start (YYYY-MM-DD). Overrides the preset time range. Earliest: 2004-01-01 for web search, 2008-01-01 for other types.

## `endDate` (type: `string`):

Optional custom range end (YYYY-MM-DD). Defaults to today.

## `region` (type: `string`):

Leave empty for worldwide. Otherwise a country code (US, GB, DE, IN...), a sub-region code (US-CA, GB-ENG, DE-BY...) or a country/region name.

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

Which Google search to measure.

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

Optional Google Trends category, by ID or exact name (e.g. 5 or 'Computers & Electronics', 71 or 'Food & Drink', 18 or 'Shopping'). Empty = all categories.

## `includeRegions` (type: `boolean`):

Add each term's interest by country (worldwide) or by sub-region (when a country is selected). Included in the price.

## `includeRelated` (type: `boolean`):

Add top and rising related queries and topics for each term, and flag Breakout ones (rising more than +5000%). Included in the price.

## `monitor` (type: `boolean`):

Turn on for scheduled runs. Each run is compared with the previous run of the same monitor, and every term gets an <code>alert</code> flag with reasons: interest moving more than the threshold, new breakout queries or topics, or the trend changing direction. Run summaries list all alerts.

## `monitorName` (type: `string`):

Use a different name for each schedule you want tracked separately. Letters, digits, dashes.

## `alertThresholdPct` (type: `integer`):

Alert when recent interest is up or down at least this much versus the period before it.

## Actor input object example

```json
{
  "searchTerms": [
    "web scraping",
    "chatgpt, gemini, claude"
  ],
  "dataMode": "standard",
  "timeRange": "past_12_months",
  "region": "",
  "searchType": "web",
  "includeRegions": true,
  "includeRelated": true,
  "monitor": false,
  "monitorName": "default",
  "alertThresholdPct": 30
}
```

# Actor output Schema

## `overview` (type: `string`):

One row per search term.

## `related` (type: `string`):

Related queries and topics, breakouts.

## `monitor` (type: `string`):

Trend-change monitor results.

## `summary` (type: `string`):

Totals, alerts and charges.

# 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": [
        "web scraping",
        "chatgpt, gemini, claude"
    ]
};

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

# Prepare the Actor input
run_input = { "searchTerms": [
        "web scraping",
        "chatgpt, gemini, claude",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("steady-scrape/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": [
    "web scraping",
    "chatgpt, gemini, claude"
  ]
}' |
apify call steady-scrape/google-trends-api --silent --output-dataset

```

## MCP server setup

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