# Google Trends Scraper: Interest, Regions & Related Queries (`t3data/google-trends`) Actor

Get Google Trends data for any keyword: interest over time, interest by country/state/city, related queries (top + rising, with Breakouts), and today's trending searches. Compare up to 5 terms. Pay only for results with data.

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

## Pricing

from $1.20 / 1,000 trends 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 & Related Queries

A **Google Trends API** with no API key and no quota. Get interest over time, interest by country, state, metro or city, related queries (top and rising, including **Breakouts**), and what's **trending right now** in any country. Compare up to 5 terms on the same 0–100 scale, just like the Trends website. **You only pay for results with data.**

| | |
|---|---|
| 💲 **Price** | $3 per 1,000 results. One result is one search line (up to 5 terms) or one trending-now country. Results without data are free. |
| ⚡ **Speed** | ~20 searches + 3 trending-now countries in about 30 seconds |
| 📥 **Input** | Keywords (one per line, or comma-separated to compare), region, time range, category, search type |
| 📤 **Output** | Time series + summary (average, latest, peak), regional breakdown, related queries, trending searches with news |
| 🌍 **Coverage** | Any country or sub-region (`US`, `DE`, `US-CA`, `US-NY-501`), worldwide, 2004–present |

### What people use it for

- **Keyword and content research**: find rising searches before they peak (`relatedQueries` with `ranking: "rising"`)
- **Product and e-commerce**: check seasonality and demand before stocking or launching (`summary.peakDate`, `interestOverTime`)
- **Brand and competitor tracking**: compare up to 5 brands in one result, week by week
- **Local targeting**: which states, metros or cities search a term most, for ads, stores or sales territories
- **AI agents and dashboards**: a ready-made `summary` per term, so an LLM or a spreadsheet doesn't have to crunch the series
- **Newsrooms and social**: today's trending searches per country, with traffic estimates and the news behind them

### How to use it

1. Add search terms, one per line. Put up to 5 on one line, separated by commas, to compare them.
2. Pick a region and time range, and optionally a search type (Web, YouTube, Shopping, News, Images) or category.
3. Click **Start**, then download the results as JSON, CSV or Excel, or fetch them through the API.

### For AI agents and automations

- **One job:** get Google Trends data (interest over time, by region, related queries) for keywords, or today's trending searches. Minimal input: `{ "searchTerms": ["air fryer"], "geo": "US" }`
- **Fast enough for a single tool call:** 1–5 searches finish in about 10 seconds; ~20 in ~30 seconds, which fits inside the Apify MCP server's default 30-second wait. For big jobs, start the run asynchronously and read the dataset when it finishes.
- **Where the results are:** dataset items (fields below). A **run summary** is in the key-value store record `OUTPUT`: `status` (`SUCCEEDED`, `PARTIAL`, `STOPPED_AT_SPEND_LIMIT`, `ABORTED`, `NO_RESULTS`, `SOURCE_UNAVAILABLE`), `results`, `errorsByCode` and a plain-English `message`.
- **Predictable billing:** pay per event. Only successful results are charged; error rows are free.
- **Respects "Max cost per run":** it never starts work your budget can't pay for, then stops cleanly with status `STOPPED_AT_SPEND_LIMIT`. Everything fetched up to that point is kept.
- **Graceful on abort and restarts:** partial results are always kept, and a platform restart resumes without duplicates or double charges.
- **Honest failures:** if the source blocks every request or changes its format, the run fails with a clear message and you pay $0, instead of quietly returning empty results.
- Works with the **Apify MCP server** (Claude, Cursor, other agents), agentic payments, and the API.

### Input examples

One keyword in the US over the past 12 months:

```json
{ "searchTerms": ["air fryer"], "geo": "US", "timeRange": "past_12_months" }
```

Compare three brands worldwide over 5 years, with city-level detail:

```json
{ "searchTerms": ["tesla, rivian, lucid"], "timeRange": "past_5_years", "regionResolution": "city" }
```

YouTube search interest for a custom date range, plus today's trending searches:

```json
{ "searchTerms": ["minecraft"], "searchType": "youtube", "timeRange": "custom", "customTimeRange": "2024-01-01 2024-12-31", "trendingNowCountries": ["US", "GB"] }
```

### Output

From a real run: `chatgpt, gemini, claude`, United States, past 12 months (arrays shortened):

```json
{
  "status": "ok",
  "type": "explore",
  "query": "chatgpt vs gemini vs claude",
  "searchTerms": ["chatgpt", "gemini", "claude"],
  "geo": "US",
  "timeRange": "today 12-m",
  "searchType": "web",
  "url": "https://trends.google.com/trends/explore?date=today+12-m&geo=US&q=chatgpt%2Cgemini%2Cclaude&hl=en-US",
  "summary": {
    "chatgpt": { "average": 77, "latest": 79, "peak": 100, "peakDate": "2025-10-19" },
    "gemini":  { "average": 28, "latest": 33, "peak": 36,  "peakDate": "2026-10-11" },
    "claude":  { "average": 19, "latest": 23, "peak": 33,  "peakDate": "2026-04-12" }
  },
  "interestOverTime": [
    { "date": "2026-10-04", "formattedTime": "Oct 4 – 10, 2026", "isPartial": false, "values": { "chatgpt": 79, "gemini": 33, "claude": 23 } }
  ],
  "regionLevel": "region",
  "interestByRegion": [
    { "geoCode": "US-CA", "geoName": "California", "values": { "chatgpt": 58, "gemini": 24, "claude": 18 } }
  ],
  "relatedQueries": [
    { "term": "chatgpt", "ranking": "top", "value": 100, "formattedValue": "100", "query": "chatgpt ai" },
    { "term": "chatgpt", "ranking": "rising", "value": 300, "formattedValue": "+300%", "query": "cancel chatgpt subscription" }
  ]
}
```

Trending now (`trendingNowCountries: ["US"]`):

```json
{
  "status": "ok",
  "type": "trendingNow",
  "geo": "US",
  "trendingCount": 10,
  "trendingSearches": [
    { "rank": 1, "title": "sonay kartal", "approxTraffic": "2000+", "startedAt": "2026-10-16T04:50:00.000Z",
      "news": [{ "title": "Wuhan Open: Sonay Kartal beats Jasmine Paolini to reach quarter-finals", "url": "https://www.bbc.com/sport/tennis/articles/c85ynx5vwq35o", "source": "BBC" }] }
  ]
}
```

| Field | Meaning |
|---|---|
| `summary` | Per term: `average`, `latest` (last complete point), `peak`, `peakDate` |
| `interestOverTime` | 0–100 per date for each term. `isPartial` marks the current, incomplete period. |
| `interestByRegion` / `regionLevel` | 0–100 per region, and which level you got (country, region, metro or city) |
| `relatedQueries` | `top` and `rising` queries per term. `formattedValue` shows `+300%` or `Breakout`. |
| `trendingSearches` | Rank, title, approximate traffic, start time, and related news articles |
| `url` | The same view on the Google Trends website |
| `status` / `errorCode` | `ok`, or why there's no data (free) |

### Cost examples

| Job | Results | Cost |
|---|---|---|
| 10 keywords | 10 | $0.03 |
| 100 keywords, each compared against 4 competitors | 100 | $0.30 |
| Daily trending-now for 20 countries for a month | 600 | $1.80 |

Set **Max cost per run** to cap any run, and the actor stops cleanly at the limit.

### Integrations

- **API**: `client.actor("t3data/google-trends").call({ searchTerms: ["air fryer"], geo: "US" })` (JS), or `client.actor("t3data/google-trends").call(run_input={"searchTerms": ["air fryer"], "geo": "US"})` (Python). Full snippets are on the **API** tab.
- **AI agents (MCP)**: available as a tool through the Apify MCP server.
- **Scheduling**: run it daily or weekly with Apify Schedules to track trends over time.
- **No-code**: Make, Zapier, n8n, Google Sheets, Slack and webhooks, through Apify integrations.
- **Export**: JSON, CSV, Excel, XML, HTML or RSS.

### Error codes (never charged)

| Code | Meaning |
|---|---|
| `NO_DATA` | Not enough search volume for this term, region and time range |
| `TOO_MANY_TERMS` | More than 5 terms on one line. Split the line. |
| `INVALID_INPUT` | Google rejected the geo, category or time range |
| `INVALID_GEO` | No trending-now feed for that country code |
| `SOURCE_UNAVAILABLE` (run status) | Every request was blocked, or the source changed its format. The run fails with $0 charged; retry later |
| `BLOCKED` | Google kept rate-limiting after every retry (rare; try again) |
| `NETWORK_ERROR` | A connection problem after every retry |

### FAQ

**Why are values 0–100, not search counts?** That's how Google Trends works. 100 is peak popularity for the selected terms, region and time, and everything else is relative to it. Put terms on the same line to compare them on one scale.

**Why do my numbers differ slightly from the website?** Google samples its data, so the same query can vary by a point or two between requests, on the website too.

**Why did the region level fall back?** Google doesn't publish every level everywhere: metro areas are US-only, and small terms have no city data. If the level you chose is empty, you get Google's default level, and `regionLevel` says which one.

**Is there an official Google Trends API?** Only a limited alpha with restricted access. This actor gives you the same data the public Trends website shows.

**Do I need a proxy?** No. A residential proxy, IP rotation and rate-limit retries are built in, and their cost is included in the price.

**Something broke?** Open an issue on the **Issues** tab with your input. Fixes usually ship within a day.

### Limits

- Values are relative (0–100), not absolute search volumes. That's a Google Trends limitation.
- Related topics aren't included, because Google returns them empty for automated clients. Related queries work.
- At most 5 terms per comparison, the same as the website.

### More from T3 Data

- [YouTube Transcripts](https://apify.com/t3data/youtube-transcripts): full transcripts, SRT and AI-ready chunks for videos, playlists and channels
- [YouTube Comments Scraper](https://apify.com/t3data/youtube-comments): comments and replies with likes, pinned and creator-hearted flags
- [YouTube Channel & Shorts Scraper](https://apify.com/t3data/youtube-channel): channel info plus every video and Short with exact views, likes and dates
- [Google News Scraper](https://apify.com/t3data/google-news): news by keyword, topic or location, with real article URLs and full text
- [Google Ads Transparency Scraper](https://apify.com/t3data/google-ads-transparency): every ad an advertiser or domain runs on Google, with dates, images and YouTube videos
- [Google Hotels Scraper](https://apify.com/t3data/google-hotels): hotel prices, ratings and booking-site prices for any city and dates

***

*This Actor is an independent tool. It is not affiliated with, endorsed by, or sponsored by Google. It only accesses publicly available Google Trends data.*

# Actor input Schema

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

One query per line. To compare terms on the same 0–100 scale (like the Trends website), put up to 5 on one line separated by commas, e.g. "bitcoin, ethereum".

## `geo` (type: `string`):

Country or region code, e.g. US, GB, DE, US-CA (California), US-NY-501 (New York metro). Leave empty for worldwide.

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

Period to analyze. Short ranges (past hour to past 7 days) return hourly or minute-level points.

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

Used only when Time range is "Custom". Format: "YYYY-MM-DD YYYY-MM-DD", e.g. "2024-01-01 2024-12-31".

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

Which Google property to measure: regular web search, Image, News, Shopping, or YouTube search.

## `category` (type: `integer`):

Optional Google Trends category ID to narrow ambiguous terms (e.g. 7 = Finance, 71 = Food & Drink, 5 = Computers & Electronics). 0 = all categories.

## `includeInterestOverTime` (type: `boolean`):

Adds the `interestOverTime` time series (0–100 per date) plus a `summary` with average, latest and peak.

## `includeInterestByRegion` (type: `boolean`):

Adds `interestByRegion`: which countries, states, metros or cities search the term most.

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

Granularity for interest by region. Automatic uses Google's default (countries for worldwide, states/provinces for a country). Metro areas (DMA) exist for the US only. If the chosen level has no data, Google's default level is used; the `regionLevel` field tells you which one you got.

## `includeRelatedQueries` (type: `boolean`):

Adds `relatedQueries`: top and rising searches people also make, with "Breakout" flags (great for keyword and content ideas).

## `trendingNowCountries` (type: `array`):

Optional. Country codes (e.g. US, GB, IN) to get what is trending in Google Search right now, with approximate search volume and related news. One result per country.

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

Language for region names and formatted dates, e.g. en-US, de, es, fr, ja.

## `maxConcurrency` (type: `integer`):

How many queries to process at the same time.

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

Residential proxy is strongly recommended — Google Trends rate-limits hard per IP. Proxy cost is included in the price.

## Actor input object example

```json
{
  "searchTerms": [
    "air fryer",
    "chatgpt, gemini, claude"
  ],
  "geo": "US",
  "timeRange": "past_12_months",
  "searchType": "web",
  "category": 0,
  "includeInterestOverTime": true,
  "includeInterestByRegion": true,
  "regionResolution": "auto",
  "includeRelatedQueries": true,
  "trendingNowCountries": [],
  "language": "en-US",
  "maxConcurrency": 8,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

One item per search query (interest over time, by region, related queries) or per trending-now country, or an error code (not charged).

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

One JSON object: status (SUCCEEDED, PARTIAL, STOPPED_AT_SPEND_LIMIT, ABORTED, NO_RESULTS, SOURCE_UNAVAILABLE), results count, failed inputs by error code, and a plain-English message.

# 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": [
        "air fryer",
        "chatgpt, gemini, claude"
    ],
    "geo": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("t3data/google-trends").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": [
        "air fryer",
        "chatgpt, gemini, claude",
    ],
    "geo": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("t3data/google-trends").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": [
    "air fryer",
    "chatgpt, gemini, claude"
  ],
  "geo": "US"
}' |
apify call t3data/google-trends --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,t3data/google-trends"
        }
    }
}
```

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/FfrdiaXlepnZtpEWM/builds/pxHM9GQwXhUGqRAg2/openapi.json