# Google Trends & Keyword Research API (`jixiaohao/google-trends-keyword-research`) Actor

Google Trends for many keywords per run: interest over time with growth %, YoY and seasonality, rising and top related queries and topics, interest by region, Trending Now, and Google Autocomplete keyword ideas. Pay per keyword. Works as an MCP server for AI agents.

- **URL**: https://apify.com/jixiaohao/google-trends-keyword-research.md
- **Developed by:** [Ji](https://apify.com/jixiaohao) (community)
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 keyword reports

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 & Keyword Research API

Give it a list of keywords; get back, per keyword, everything you need to judge search demand:

- **Interest over time** with ISO dates, plus computed **growth %, year-over-year growth, trend direction, peak, volatility and seasonal peak month**
- **Related queries and related topics**, top and rising (including "Breakout")
- **Interest by region** (states for a country, countries for worldwide)
- **Keyword ideas from Google Autocomplete**, expanded with question and intent modifiers (`how`, `best`, `vs`, `for`, `alternative`, `free`...)
- **Trending Now** for a country (optional)
- **Side-by-side comparison** of up to 5 keywords on one 0–100 scale (optional)

> Google Trends values are a 0–100 index relative to the highest point in the chosen geo and timeframe. They are not absolute search volumes. Every item carries a `valueNote` saying so.

### Why this actor

Google has no public Trends API and `pytrends` is archived, so Trends scrapers break when Google rate-limits them. This actor warms Google cookies, follows the explore → widget-token flow, and rotates proxy sessions with exponential backoff on every 429. When one part fails (say, region data), you still get the rest, with the reason in `errors`; you are only charged for items that contain data.

#### Benchmark

On 26 Oct 2026 we ran the same 50 keywords (US, past 12 months) through this actor and the most-used Google Trends actors on the Store:

| | Keywords with data | Run time | Notes |
| --- | --- | --- | --- |
| **This actor** | **50 / 50** | **175 s** | One run, all 50 keywords, plus related queries, regions and Autocomplete ideas |
| Most-used Trends actor | 34 / 50 | 157 s | One keyword per run, 50 runs |
| Apify's Google Trends scraper | 1 / 50 | 621 s (stopped) | Stalled on rate limits |
| Another all-keywords actor | 50 / 50 | 831 s | About 20x the cost per keyword |
| Two other actors | — | — | Accept at most 5 keywords per run |

The script and raw results are in [`bench/`](bench/).

### Input

| Field | Default | Notes |
| --- | --- | --- |
| `keywords` | — | One report per keyword. Free-plan runs are capped at 10. |
| `geo` | `US` | Two-letter country code; empty = worldwide. |
| `language` | `en` | |
| `timeframe` | `today 12-m` | `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, `all` |
| `category` | `0` | Google Trends category ID. |
| `searchProperty` | web | `youtube`, `images`, `news`, `froogle` (Shopping). |
| `includeTrends` / `includeRegions` | `true` | |
| `includeYoY` | `true` | Year-over-year growth. Adds one Trends query per keyword for timeframes under 5 years. |
| `includeTrendingNow` | `false` | Works with an empty keyword list. |
| `includeAutocomplete` | `true` | |
| `autocompleteExpansion` | `questions` | `none` (1 query), `questions` (23), `full` (49, adds a–z). |
| `compareInOneChart` | `false` | Groups of 5. |
| `maxConcurrency` | `3` | Keywords researched in parallel (1–5), each on its own proxy session. |
| `proxyConfiguration` | Residential | Strongly recommended. |

#### Example: agent call

```json
{
  "keywords": ["ai video editor", "notion templates", "cold email software"],
  "geo": "US",
  "timeframe": "today 12-m",
  "autocompleteExpansion": "questions",
  "compareInOneChart": true
}
```

### Output

One item per keyword (`type: "keyword"`), plus optional `trendingNow` and `comparison` items.

```json
{
  "type": "keyword",
  "keyword": "notion templates",
  "geo": "US",
  "timeframe": "today 12-m",
  "valueNote": "Google Trends values are a 0-100 index ...",
  "metrics": {
    "dataPoints": 52, "average": 61.4, "latest": 72, "peak": 100,
    "peakPeriod": "2026-01-04", "growthPct": 18.2, "trendDirection": "rising",
    "slopePerPeriod": 0.41, "volatility": 0.17, "seasonalPeakMonth": "Jan",
    "yoyGrowthPct": 12.5, "yoyDirection": "stable",
    "yoyWindow": { "from": "2026-09-27", "to": "2026-10-18", "comparedWithFrom": "2025-09-28", "comparedWithTo": "2025-10-19" }
  },
  "interestOverTime": [{ "date": "2025-10-26", "formattedTime": "Oct 26 – Nov 1, 2025", "value": 58, "isPartial": false }],
  "relatedQueries": {
    "top": [{ "query": "free notion templates", "value": 100, "formattedValue": "100" }],
    "rising": [{ "query": "notion ai templates", "value": 4250, "formattedValue": "Breakout" }]
  },
  "relatedTopics": { "top": [], "rising": [] },
  "interestByRegion": [{ "geoCode": "US-WA", "geoName": "Washington", "value": 100 }],
  "risingQueryTerms": ["notion ai templates"],
  "keywordIdeas": [{ "suggestion": "notion templates for students", "sources": ["seed", "suffix:for"], "rank": 2, "timesSuggested": 2 }],
  "keywordIdeasCount": 87,
  "errors": [],
  "scrapedAt": "2026-10-26T17:30:00.000Z"
}
```

`growthPct` compares the average of the last quarter of the window with the first quarter. `trendDirection` is `rising` at +15% or more, `falling` at −15% or less, otherwise `stable`. The partial (in-progress) last period is excluded from metrics.

`growthPct` describes the shape of the chosen window, so a seasonal keyword looks like it is "rising" as its season approaches. `yoyGrowthPct` compares the latest 4 weeks with the same 4 weeks one year earlier, which is the number to use for "is this market actually growing?".

### Use it from an AI agent (Standby / MCP)

The actor also runs in Apify Standby mode as an always-on web server, so agents get answers in one HTTP call with no run to start or dataset to fetch.

**MCP** (streamable HTTP, stateless): `POST https://<your-standby-url>/mcp` with your Apify token as `Authorization: Bearer <token>`.

| Tool | What it returns |
| --- | --- |
| `research_keywords` | 1–5 keywords: metrics, rising/top queries and topics, top regions, keyword ideas |
| `compare_keywords` | 2–5 keywords on one 0–100 scale, ranked by average interest |
| `trending_now` | Today's trending searches for a country |

Every tool takes `geo`, `timeframe`, `language`, `searchProperty` and `detail` (`summary` by default, which returns metrics and top-10 lists to save tokens, or `full`).

**REST**

```
GET /research?keywords=notion%20templates,crm&geo=US&timeframe=today%2012-m&detail=summary
GET /compare?keywords=notion,obsidian,evernote
GET /trending-now?geo=GB
```

Standby calls are charged with the same events as batch runs, and only for results that contain data.

### Pricing (pay per event)

| Event | When |
| --- | --- |
| `keyword-report` | One keyword item with Trends or Autocomplete data |
| `comparison-report` | One comparison item (up to 5 keywords) |
| `trending-now-report` | One Trending Now item |

Items that come back empty are not charged. The run stops cleanly when your maximum charge is reached.

### Local development

```bash
npm install
npm test
apify run --input '{"keywords":["notion templates"]}'
```

# Actor input Schema

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

Keywords or phrases to research. One dataset item is produced per keyword. Free Apify plan runs are capped at 10 keywords.

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

Two-letter country code (e.g. US, GB, DE). Leave empty for worldwide. Also used as the Autocomplete market.

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

Language code for Trends and Autocomplete (e.g. en, de, es).

## `timeframe` (type: `string`):

Google Trends time range.

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

Google Trends category ID (0 = all categories).

## `searchProperty` (type: `string`):

Which Google search to measure.

## `includeTrends` (type: `boolean`):

Interest over time, growth metrics, related queries and topics.

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

Sub-region breakdown (states for a country, countries for worldwide).

## `includeYoY` (type: `boolean`):

Compare the latest 4 weeks with the same weeks a year earlier, so seasonal keywords aren't mistaken for growing ones. Adds one Trends query per keyword when the timeframe is shorter than 5 years.

## `includeTrendingNow` (type: `boolean`):

Add one item with today's trending searches for the selected country (approximate traffic, start time, news links). Works with an empty keyword list.

## `includeAutocomplete` (type: `boolean`):

Google Autocomplete suggestions for the keyword plus the expansion modifiers below.

## `autocompleteExpansion` (type: `string`):

How many query variants to send to Autocomplete per keyword. 'questions' adds how/what/why/best/vs style prefixes and suffixes; 'full' also adds a-z.

## `compareInOneChart` (type: `boolean`):

Also query Trends with up to 5 keywords at once so their 0-100 values are directly comparable. Adds one extra item with type 'comparison' per group of 5.

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

Google rate-limits Trends aggressively. Residential proxies are strongly recommended.

## `maxRetries` (type: `integer`):

Retries with a fresh proxy session on 429 or blocked responses.

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

How many keywords to research at once, each on its own proxy session. Higher is faster but more likely to hit Google rate limits.

## Actor input object example

```json
{
  "keywords": [
    "ai video editor",
    "notion templates"
  ],
  "geo": "US",
  "language": "en",
  "timeframe": "today 12-m",
  "category": 0,
  "searchProperty": "",
  "includeTrends": true,
  "includeRegions": true,
  "includeYoY": true,
  "includeTrendingNow": false,
  "includeAutocomplete": true,
  "autocompleteExpansion": "questions",
  "compareInOneChart": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "maxRetries": 6,
  "maxConcurrency": 3
}
```

# Actor output Schema

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

No description

## `results` (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 = {
    "keywords": [
        "ai video editor",
        "notion templates"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("jixiaohao/google-trends-keyword-research").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": [
        "ai video editor",
        "notion templates",
    ],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("jixiaohao/google-trends-keyword-research").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": [
    "ai video editor",
    "notion templates"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call jixiaohao/google-trends-keyword-research --silent --output-dataset

```

## MCP server setup

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

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/xgfYBDrb7YtPe4hbK/builds/nkGuXsEOxdglCUaPL/openapi.json