# Google Trends API – Bulk Keywords, Compare & Trending Now (`henryklimes/google-trends`) Actor

Google Trends data as clean rows: interest over time, interest by region, top and rising related queries for hundreds of keywords per run. Compare more than 5 keywords on one scale, plus Trending Now by country. pytrends alternative, pay per keyword, no start fee.

- **URL**: https://apify.com/henryklimes/google-trends.md
- **Developed by:** [Jindrich Klimes](https://apify.com/henryklimes) (community)
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.25 / 1,000 keyword rows

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 – Bulk Keywords, Compare & Trending Now

Get Google Trends data as clean rows: **interest over time, interest by region and top and rising related queries** for hundreds of keywords in one run. **Compare more than 5 keywords on one shared scale** (Google stops at 5), and pull **Trending Now** searches with traffic and news for any country. A hosted pytrends alternative: no code, no 429 headaches, export to JSON, CSV or Excel or call it as an API.

### What you get

- **Interest over time** – the full timeline (0–100) plus ready-made summary columns: average, peak and peak date, latest value, change % and trend direction (rising / falling / stable)
- **Interest by region** – countries, states, cities or US metro areas (DMA), highest first
- **Related queries** – top and rising, with Breakout flags
- **Compare mode** – 2 to 50 keywords on one 0–100 scale, chained through shared anchor keywords, with a rank column
- **Trending Now** – today's trending searches per country with approximate traffic, start time, picture and news articles
- **Bulk** – up to 500 keywords × up to 50 geos per run; every row also links to the same view on trends.google.com
- **Empty and failed keywords are free** – rows with `no_data` or `error` are never charged

### Modes

| Mode | Use it for | Rows |
| --- | --- | --- |
| `keyword` | Keyword research, seasonality, regional demand, related queries | One per keyword × geo, each scaled 0–100 on its own |
| `compare` | Which of these keywords is searched most? | One per keyword, all on one shared scale |
| `trendingNow` | What is trending right now in the US, CZ, DE …? | One per trending search |

### Input

```json
{
  "mode": "keyword",
  "keywords": ["matcha", "chai", "oat milk"],
  "geos": ["US", "GB"],
  "timeRange": "today 12-m",
  "includeRegions": true,
  "includeRelatedQueries": true
}
```

| Field | Default | Description |
| --- | --- | --- |
| `mode` | `keyword` | `keyword`, `compare` or `trendingNow` |
| `keywords` | — | Search terms (500 max in keyword mode, 50 in compare mode). Duplicates are removed. |
| `startUrls` | — | Google Trends explore URLs; keywords, geo, date, category and property are read from each link |
| `geos` | worldwide | Country codes (`US`, `CZ`), sub-regions (`US-CA`) or empty for worldwide. Trending Now defaults to `US`. |
| `timeRange` | `today 12-m` | `now 1-H`, `now 4-H`, `now 1-d`, `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, `all` or `2025-01-01 2025-06-30` |
| `category` | `0` | Google Trends category id (`cat=` in a Trends URL) |
| `property` | `web` | `web`, `images`, `news`, `youtube` or `shopping` |
| `includeRegions` | `true` | Add interest by region |
| `regionResolution` | `auto` | `auto`, `COUNTRY`, `REGION`, `CITY` or `DMA` |
| `includeRelatedQueries` | `true` | Add top and rising related queries |
| `includeRelatedTopics` | `false` | Best-effort: Google often returns related topics empty for automated requests |
| `maxTrendingItems` | `50` | Trending searches per country (Google's feed currently lists about 10) |
| `maxSessions` | `2` | Parallel Google sessions (1–3) |
| `proxyConfiguration` | Apify Proxy | Datacenter proxy works well; each session gets its own IP |
| `residentialFallback` | `false` | Retry a still-rate-limited keyword once through residential proxy |

### Output

Keyword mode (arrays shortened):

```json
{
  "mode": "keyword",
  "keyword": "matcha",
  "geo": "US",
  "time_range": "today 3-m",
  "status": "ok",
  "average_interest": 72.42,
  "peak_value": 100,
  "peak_date": "2026-09-05",
  "latest_value": 65,
  "latest_date": "2026-11-16",
  "latest_is_partial": true,
  "change_percent": -19.2,
  "trend_direction": "falling",
  "timeline": [{ "date": "2026-08-16", "value": 93, "is_partial": false }],
  "regions": [{ "geo_code": "US-HI", "name": "Hawaii", "value": 100 }],
  "related_queries_top": [{ "query": "matcha me", "value": 100 }],
  "related_queries_rising": [{ "query": "rok matcha nyc", "value": 10250, "formatted_value": "Breakout", "is_breakout": true }],
  "trends_url": "https://trends.google.com/trends/explore?q=matcha&geo=US&date=today+3-m&hl=en-US"
}
```

Compare mode adds `rank`, `compared_keywords`, `anchor_keyword`, `precision` and `comparison_group`. Trending Now rows have `geo`, `rank`, `title`, `approx_traffic`, `approx_traffic_min`, `started_at`, `picture` and `news`.

`status` is `ok`, `no_data` (Google has too little search volume for that keyword, geo and time range) or `error` (with `error.code` such as `rate_limited`). A run summary is saved to the `OUTPUT` record.

### How to compare more than 5 keywords in Google Trends

Google Trends compares at most 5 terms at a time, and every comparison is rescaled to its own 0–100. In `compare` mode this Actor first sizes all keywords, sorts them, and then runs batches of 5 that each share one keyword with the previous batch. The shared keyword links the batches, so all values end up on one scale where the biggest keyword peaks at 100. Keywords too small to measure next to much bigger ones are re-measured in a later batch with similar-sized keywords; anything still below Google's resolution is flagged `precision: "low"`.

### Bulk Google Trends for keyword research and SEO

Paste hundreds of keywords and several countries in `keyword` mode. Each keyword gets its own 0–100 timeline plus `average_interest`, `change_percent` and `trend_direction`, so you can sort a whole keyword list by momentum in a spreadsheet and spot seasonal peaks. Rising related queries (including Breakout ones) are a quick source of new content ideas.

### Trending searches today by country

`trendingNow` returns Google's Trending Now feed for each country in `geos`: the search, approximate traffic (e.g. `20000+`), when it started, a picture and up to a few news articles. Schedule it hourly or daily on Apify to build your own trend history.

### Looking for a pytrends alternative?

pytrends is unmaintained and hits 429 errors quickly. This Actor keeps a cookie session per proxy IP, paces itself to about one request per second, honours `Retry-After`, backs off, switches to a fresh session after repeated rate limits and retries still-blocked keywords later in the run. You get the same data (interest over time, by region, related queries) as rows, without running Python or managing proxies, and you can call it from any language through the Apify API.

### Ready-made example tasks

Open one, check the prefilled input, and run it in one click:

- [pytrends alternative: bulk Google Trends interest over time](https://apify.com/henryklimes/google-trends/examples/pytrends-alternative-bulk-google-trends)
- [Keyword research with rising Google Trends queries](https://apify.com/henryklimes/google-trends/examples/keyword-research-rising-queries-google-trends)
- [Compare more than 5 keywords in Google Trends](https://apify.com/henryklimes/google-trends/examples/compare-more-than-5-keywords-google-trends)
- [Brand vs competitors: Google Trends interest on one scale](https://apify.com/henryklimes/google-trends/examples/brand-vs-competitors-google-trends)
- [Trending searches today by country](https://apify.com/henryklimes/google-trends/examples/trending-searches-today-by-country)

### Use cases

- Keyword and content research: which topics are rising, where and when
- Product and market research: seasonality and regional demand
- Brand monitoring: your brand vs competitors on one scale
- News and social teams: what is trending right now per country
- Data pipelines and dashboards: scheduled runs, JSON/CSV exports, API access

### Pricing

Pay per result: **$0.25 per 1,000 keyword rows** (about 6 CZK; $0.00025 per keyword × geo, or per keyword in a comparison) and **$0.10 per 1,000 Trending Now rows**. No start fee. `no_data` and `error` rows are free.

- **Example**: 500 keywords in 2 countries = 1,000 rows = $0.25
- **Quick test**: 20 keywords = $0.005

### FAQ

**Are the numbers search volumes?** No. Google Trends gives relative interest (0–100) within the chosen geo and time range, not absolute searches. Use `compare` mode to see keywords relative to each other.

**Why do my values differ slightly from the website?** Google samples its data, so repeated requests can differ by a few points, especially for small keywords.

**Why are related topics empty?** Google often withholds related topics from automated requests. Related queries are returned reliably; `related_topics_available` shows whether topics came back.

**How fast is it?** Roughly 5–6 seconds per keyword per session (several Google requests each, paced to avoid rate limits). With 2 sessions, 100 keywords take about 5 minutes. Turn off regions or related queries to go faster.

**How is `change_percent` calculated?** It compares the average of the last quarter of the timeline with the first quarter. For seasonal keywords over 12 months (e.g. last year's Black Friday in the first quarter) use a shorter `timeRange` or look at `peak_date` and the timeline.

**Why are Wyoming or Kansas at the top of so many US region lists?** That is what Google Trends itself returns right now, from every network we tested. A likely cause is automated and data-center search traffic, which weighs heavily in small states. Use `regionResolution: "DMA"` or compare relative values instead of reading only the first region.

**What happens when Google rate-limits?** Each session waits (honouring `Retry-After`), backs off and switches to a fresh cookie and IP. A keyword that is still blocked goes to the back of the queue and is retried after a cooldown, up to two more times. Only then does it return a free `error` row.

**What does `no_data` mean?** Google has too little search volume for that keyword in that geo and time range. These rows are free.

### Support

Found a keyword or geo that fails? Open an issue on the Actor page with the input you used.

# Actor input Schema

## `mode` (type: `string`):

<b>keyword</b>: interest over time, by region and related queries for each keyword separately (each keyword scaled 0-100 on its own).<br><b>compare</b>: puts 2-50 keywords on one scale. Google allows only 5 per comparison; more are chained through shared anchor keywords.<br><b>trendingNow</b>: current trending searches with traffic and news for each country in Geos (keywords are ignored).

## `keywords` (type: `array`):

Search terms, up to 500 in keyword mode and 50 in compare mode. Duplicates are removed.

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

Paste trends.google.com/trends/explore links (keyword mode). Keywords, geo, date, category and property are read from each URL.

## `geos` (type: `array`):

Country codes (US, CZ, DE), sub-regions (US-CA) or empty for worldwide. In keyword mode each keyword runs for every geo. Trending Now needs country codes (defaults to US).

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

One of: now 1-H, now 4-H, now 1-d, now 7-d, today 1-m, today 3-m, today 12-m, today 5-y, all - or a custom range "2025-01-01 2025-06-30". Ignored in Trending Now.

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

Google Trends category id (0 = all categories), e.g. 71 = Food & Drink, 7 = Finance. Take it from the cat= parameter of a Trends URL.

## `property` (type: `string`):

Which Google search to measure.

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

Add the regions list (0-100 per country/state/city).

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

Granularity of interest by region.

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

Add top and rising related queries, including Breakout ones.

## `includeRelatedTopics` (type: `boolean`):

Ask for related topics too. Google often returns this list empty for automated requests; related_topics_available tells you whether it came back.

## `maxTrendingItems` (type: `integer`):

Trending Now only. Google's feed currently lists about 10 per country.

## `maxSessions` (type: `integer`):

Independent Google sessions working in parallel, each paced to about 1 request per second. More sessions = faster, but a higher chance of rate limits.

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

Apify datacenter proxy works well for Google Trends. Each session gets its own IP.

## `residentialFallback` (type: `boolean`):

When a keyword is still rate-limited after all retries, try it once more through Apify residential proxy. Slower and uses residential proxy traffic on your account.

## Actor input object example

```json
{
  "mode": "keyword",
  "keywords": [
    "matcha",
    "chai",
    "oat milk"
  ],
  "geos": [
    "US"
  ],
  "timeRange": "today 12-m",
  "category": 0,
  "property": "web",
  "includeRegions": true,
  "regionResolution": "auto",
  "includeRelatedQueries": true,
  "includeRelatedTopics": false,
  "maxTrendingItems": 50,
  "maxSessions": 2,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "residentialFallback": false
}
```

# Actor output Schema

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

One row per keyword x geo, compared keyword or trending search

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

Rows ok / without data / errors, Google requests and rate limits

# 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 = {
    "keywords": [
        "matcha",
        "chai",
        "oat milk"
    ],
    "geos": [
        "US"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("henryklimes/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 = {
    "keywords": [
        "matcha",
        "chai",
        "oat milk",
    ],
    "geos": ["US"],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("henryklimes/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 '{
  "keywords": [
    "matcha",
    "chai",
    "oat milk"
  ],
  "geos": [
    "US"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call henryklimes/google-trends --silent --output-dataset

```

## MCP server setup

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