# Keyword Research for AI Agents: Google Trends + Autocomplete (`cleandata-labs/seo-keyword-research-for-agents`) Actor

Keyword ideas from Google Autocomplete (a-z and question expansion) plus Google Trends 12-month interest, direction and rising queries, in one compact JSON per keyword with a plain-English summary. Works as an MCP tool. No API key. Errors are free.

- **URL**: https://apify.com/cleandata-labs/seo-keyword-research-for-agents.md
- **Developed by:** [CleanData Labs](https://apify.com/cleandata-labs) (community)
- **Categories:** SEO tools, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 keyword ideas

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

## Keyword Research for AI Agents: Google Trends + Autocomplete

### What does it do?

Give it one or more seed keywords and a country. For each seed you get **one compact JSON result** that combines:

- **Keyword ideas from Google Autocomplete**: the seed itself, question words (what, how, why, is, can, best), modifiers (vs, for, near) and the alphabet (seed + a ... z). Duplicates are merged.
- **Google Trends for the seed**: average, latest and peak interest, the overall direction (rising, falling, stable), recent momentum and whether interest is spiky or seasonal, for the past 12 months by default.
- **Top and rising related searches from Google Trends**, with growth % and the "Breakout" flag.
- Optionally, a **Trends comparison** of the seed with its top suggestions on one shared 0-100 scale.
- A short plain-English **`summary`** an AI agent can quote directly.

It needs no Google account and no API key. Use it as a free-standing **Google Trends API alternative** for keyword ideas, or plug it into Claude, ChatGPT, Cursor or any MCP client as a keyword research tool.

### What it is not

This Actor does **not** return absolute monthly search volume or CPC. Google Trends values are relative interest (0-100), and Autocomplete shows what people type, not how often. If you need volume numbers, use a Keyword Planner based tool next to this one.

### How to use it

1. Click **Try for free** and sign in to Apify (a free account works).
2. Add your **Seed keywords**, e.g. `electric bike`.
3. Set the **Country** (`US`, `GB`, `DE`, `RO` ...; `UK` also works) and the **Language** (`en`, `de`, `ro` ...).
4. Pick the **Autocomplete depth**: `basic`, `questions` or `full` (default).
5. Click **Start**. Download results as JSON, CSV or Excel. Choose **Output mode: flat** for one row per keyword in a spreadsheet.

### Input example

```json
{
  "keywords": ["electric bike", "cargo bike"],
  "country": "US",
  "language": "en",
  "timeRange": "today 12-m",
  "expansion": "full",
  "compareTopSuggestions": 2,
  "maxKeywordsPerSeed": 100,
  "outputMode": "compact"
}
```

| Field | What it does | Default |
|---|---|---|
| `keywords` | Seed phrases, one result each (max 100 per run). Always pass your own; the default is only a demo | `["electric bike"]` |
| `country` | 2-letter code, `""` = worldwide | `US` |
| `language` | Language of suggestions and question words | `en` |
| `timeRange` | Trends period: `now 7-d`, `today 1-m`, `today 3-m`, `today 12-m`, `today 5-y`, `all` | `today 12-m` |
| `customTimeRange` | Exact period `YYYY-MM-DD YYYY-MM-DD` (overrides `timeRange`) | – |
| `expansion` | `basic` (2 lookups), `questions` (~11), `full` (~37) | `full` |
| `includeTrends` | Add Google Trends data | `true` |
| `compareTopSuggestions` | Compare the seed with 0-4 top ideas on one Trends scale | `0` |
| `maxKeywordsPerSeed` | Cap on the merged keyword list | `100` |
| `outputMode` | `compact` (one result per seed) or `flat` (one row per keyword) | `compact` |
| `questionPrefixes`, `modifierSuffixes` | Your own words instead of the built-in lists | built-in |

Built-in question and modifier words exist for English, Romanian, German, French, Spanish, Italian, Portuguese, Dutch and Polish. Other languages fall back to English words; pass your own with `questionPrefixes` and `modifierSuffixes`.

### Output

In **compact** mode each seed gives one item (shortened):

```json
{
  "type": "keyword_research",
  "seed": "electric bike",
  "geo": "US",
  "language": "en",
  "timeRange": "today 12-m",
  "expansion": "full",
  "summary": "\"electric bike\" (US, past 12 months): Google Trends interest trended up over the period (+35% fitted change); average 30.7/100, latest 13/100, peak in the period starting 2026-04-12. Recent momentum is down (-66% for the latest quarter of the period vs the quarter before). Interest is spiky or seasonal (peak is 3x+ the average). Found 337 related keywords (showing 99); 50 of those shown are questions. Rising searches: \"yozma in 10\" (Breakout), \"yozma\" (+3950%), \"electric mini bike\" (+300%). Top autocomplete ideas: \"electric bike for adults\", \"electric bike for kids\", \"electric bikes for sale\", \"electric bikes near me\", \"electric bikes at walmart\". Common questions: \"what electric bikes are street legal\", \"what electric bike should i buy\", \"what electric bike has the longest range\". Trends values are relative (0-100), not absolute search volumes.",
  "trends": {
    "status": "ok",
    "interest": {
      "average": 30.7,
      "latest": 13,
      "latestDate": "2026-10-18",
      "peak": 100,
      "peakDate": "2026-04-12",
      "low": 10,
      "direction": "rising",
      "trendChangePercent": 35,
      "recentChangePercent": -66,
      "recentMomentum": "down",
      "slopePerPoint": 0.208,
      "pointCount": 52,
      "isSpiky": true
    },
    "topQueries": [
      {
        "query": "electric dirt bike",
        "value": 100
      },
      {
        "query": "dirt bike",
        "value": 97
      },
      {
        "query": "electric mini bike",
        "value": 50
      }
    ],
    "risingQueries": [
      {
        "query": "yozma in 10",
        "growthPercent": null,
        "isBreakout": true
      },
      {
        "query": "yozma",
        "growthPercent": 3950,
        "isBreakout": false
      },
      {
        "query": "electric mini bike",
        "growthPercent": 300,
        "isBreakout": false
      }
    ],
    "trendsUrl": "https://trends.google.com/trends/explore?q=electric%20bike&date=today%2012-m&geo=US"
  },
  "comparison": null,
  "keywordCount": 100,
  "keywordsFoundBeforeCap": 338,
  "autocompleteIdeaCount": 100,
  "questionCount": 50,
  "keywords": [
    {
      "keyword": "electric bike",
      "sources": [
        "seed",
        "autocomplete"
      ],
      "foundVia": "seed",
      "autocompletePosition": 1,
      "isQuestion": false,
      "wordCount": 2,
      "trendsAverage": 30.7,
      "trendsLatest": 13,
      "trendsDirection": "rising"
    },
    {
      "keyword": "electric bike for adults",
      "sources": [
        "autocomplete"
      ],
      "foundVia": "seed",
      "autocompletePosition": 1,
      "isQuestion": false,
      "wordCount": 4
    },
    {
      "keyword": "electric bike for kids",
      "sources": [
        "autocomplete"
      ],
      "foundVia": "seed",
      "autocompletePosition": 2,
      "isQuestion": false,
      "wordCount": 4
    },
    {
      "keyword": "what electric bikes are street legal",
      "sources": [
        "autocomplete"
      ],
      "foundVia": "prefix:what",
      "autocompletePosition": 1,
      "isQuestion": true,
      "wordCount": 6
    },
    {
      "keyword": "fat tire electric bike",
      "sources": [
        "trends_top",
        "trends_rising"
      ],
      "foundVia": "trends_top",
      "isQuestion": false,
      "wordCount": 4,
      "trendsTopValue": 30,
      "trendsRisingPercent": 250
    }
  ],
  "warnings": [],
  "note": "Trends values are relative interest (0-100, 100 = peak in this period/location), not search volumes.",
  "dataSources": [
    "google_autocomplete",
    "google_trends"
  ],
  "scrapedAt": "2026-10-28T16:50:00+00:00"
}
```

Main fields:

- `summary`: plain-English overview, safe to quote.
- `trends.status`: `ok`, `no_data` (term too rare for Trends), `failed` (see `warnings`) or `skipped`.
- `trends.interest`: `average`, `latest`, `peak`, `peakDate`, `low`, `direction` (`rising` / `falling` / `stable`, from a straight-line fit over the period; `too_low` or `no_data` when values are near zero), `trendChangePercent`, `recentChangePercent` and `recentMomentum` (latest quarter of the period vs the quarter before), `isSpiky`.
- `keywordCount`, `keywordsFoundBeforeCap`, `autocompleteIdeaCount`, `questionCount`: quick counts.
- `comparison`: only with `compareTopSuggestions` > 0; the seed and its top ideas on one shared 0-100 scale (`averages`, `latest`, `directions`).
- `keywords`: the merged, deduplicated list. The seed comes first, then Autocomplete ideas in the order found, then queries that only Google Trends returned.
- `warnings`: anything that went wrong but did not stop the result, e.g. Trends rate-limited.

Fields of each keyword (the same names in both output modes):

| Field | Meaning |
|---|---|
| `keyword` | The search phrase |
| `sources` | `seed`, `autocomplete`, `trends_top`, `trends_rising` |
| `foundVia` | Which lookup found it first: `seed`, `prefix:how`, `suffix:vs`, `alphabet:a`, `trends_top`, `trends_rising` |
| `autocompletePosition` | Best position in an Autocomplete list (1 = first) |
| `isQuestion` | Starts with a question word or ends with `?` |
| `wordCount` | Number of words |
| `trendsTopValue` | Value in Trends "top" related queries (0-100) |
| `trendsRisingPercent` | Growth % in Trends "rising" related queries |
| `isBreakout` | Trends shows "Breakout" (growth above 5000%) |
| `trendsAverage`, `trendsLatest`, `trendsDirection` | Set for the seed, and for compared keywords on a shared scale |

In compact mode, empty optional fields (null or false) are left out to save tokens. In **flat** mode every row has all columns, plus `seed`, `rank` and the seed's Trends numbers (`seedAverage`, `seedLatest`, `seedDirection`, `seedTrendChangePercent`). The `summary` and `warnings` are on the first row of each seed.

### Use with AI agents (MCP)

This Actor works as a ready-made tool for Claude, ChatGPT, Cursor, VS Code and other MCP clients through the official [Apify MCP server](https://docs.apify.com/platform/integrations/mcp). The agent gets one tool, `cleandata-labs--seo-keyword-research-for-agents`, with the input fields above. You pay the normal pay-per-event price from your Apify account.

**MCP server URL with only this Actor:**

```text
https://mcp.apify.com?tools=cleandata-labs/seo-keyword-research-for-agents
```

On first connection your client opens the Apify sign-in (OAuth). To use an API token instead, send the header `Authorization: Bearer <YOUR_APIFY_TOKEN>`.

**Claude (claude.ai and Claude Desktop):** Settings → Connectors → Add custom connector. Name: `Keyword Research`, Remote MCP server URL: the URL above.

**Claude Desktop with a local config file** (`claude_desktop_config.json`, needs Node.js 18+):

```json
{
  "mcpServers": {
    "keyword-research": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server", "--tools", "cleandata-labs/seo-keyword-research-for-agents"],
      "env": { "APIFY_TOKEN": "<YOUR_APIFY_TOKEN>" }
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "keyword-research": { "url": "https://mcp.apify.com?tools=cleandata-labs/seo-keyword-research-for-agents" }
  }
}
```

**Claude Code:**

```bash
claude mcp add --transport http keyword-research "https://mcp.apify.com?tools=cleandata-labs/seo-keyword-research-for-agents"
```

**VS Code** (`.vscode/mcp.json`):

```json
{
  "servers": {
    "keyword-research": { "type": "http", "url": "https://mcp.apify.com?tools=cleandata-labs/seo-keyword-research-for-agents" }
  }
}
```

#### Tips for agents

- Smallest useful input: `{"keywords": ["electric bike"], "country": "US"}`.
- One seed with `expansion: "full"` usually takes 20-40 seconds, longer if Google slows down Trends. For a quick answer use `expansion: "questions"` or `"basic"`, or `includeTrends: false`.
- Quote the `summary` field, then use `keywords` for details. Filter `isQuestion: true` for FAQ and content ideas, and `trendsRisingPercent` / `isBreakout` for what is growing.
- Keep `maxKeywordsPerSeed` around 30-50 if context space matters.
- Trends numbers are relative interest, not search volume. Say so when you report them.

#### Example prompts

1. "Use the keyword research tool for "electric bike" in the US. Is interest growing, and which questions do people ask most?"
2. "Find keyword ideas for "cafea" in Romania (language ro) and list the 10 most useful ones for a coffee shop blog."
3. "Compare "air fryer" with its top 3 suggestions on Google Trends in the UK over the past 5 years."

### How much does it cost?

This Actor uses **pay-per-event pricing**. You pay only for what you get:

| Event | Price | When |
|---|---|---|
| Keyword ideas (one seed) | **$0.002** | The seed returned Autocomplete ideas |
| Google Trends insights (one seed) | **$0.002** | The seed returned Trends data |

So a full result costs **$0.004 per seed keyword** ($4 per 1,000), and a seed where Google Trends failed costs $0.002. Error rows and seeds with no data at all are free. The flat output mode costs the same as compact. Apify also charges its standard Actor start event ($0.00005 per run).

Set a **maximum cost per run** in the run options. The Actor checks the limit before each seed and stops cleanly when it is reached.

### Reliability

- Apify Proxy is on by default. Rate-limited requests (HTTP 429/403) are retried with a new session and IP, with growing pauses. If the proxy itself is refused, the run continues without it.
- If Google Trends keeps refusing, you still get the Autocomplete ideas, with a clear warning and a lower price.
- For large batches (more than ~20 seeds), use the **Residential** proxy group and keep the default delays.

### Limitations

- No absolute search volume, CPC or keyword difficulty.
- Autocomplete suggestions are personalised and change over time; results can differ slightly between runs.
- The a-z expansion is designed for Latin alphabets.
- Google Trends may have no data for rare or long-tail phrases (`trends.status: "no_data"`).
- Uses public, unofficial Google endpoints, which Google can change without notice.

### Is it legal?

The Actor reads public, aggregated data that Google shows to any visitor (Autocomplete suggestions and Google Trends). It does not log in and does not collect personal data. It is not affiliated with or endorsed by Google. Check Google's Terms of Service and the law that applies to you, and ask a lawyer if you are unsure. You are responsible for how you use the data.

### FAQ

**Is this the official Google Trends API?** No. Google's official Trends API is in limited alpha. This Actor reads the public trends.google.com website and the public Autocomplete endpoint.

**Do I need an API key?** No Google key. You need an Apify account to run it.

**Why is `latest` low when `direction` is rising?** `direction` describes the whole period (a straight-line fit). `recentMomentum` describes the last part of it. Seasonal terms, like bikes in autumn, can be up over the year and down right now; the summary mentions both.

**Can I add search volume later?** The output is designed so a volume source can be added as extra fields without renaming anything.

# Actor input Schema

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

Short search phrases to research, one result per phrase. Example: \["electric bike", "cargo bike"]. Max 100 per run; duplicates are ignored.

## `country` (type: `string`):

2-letter country code for Autocomplete and Trends. Example: "US", "GB" ("UK" also works), "DE", "RO". Use "" for worldwide. Default "US".

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

Language code for suggestions and question words. Example: "en", "ro", "de", "pt-BR". Default "en". Match it to the country for best results.

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

Period for the Google Trends interest summary. Default "today 12-m" (past 12 months). Use "today 5-y" to see seasonality over several years.

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

Optional exact period that overrides timeRange. Format "YYYY-MM-DD YYYY-MM-DD", e.g. "2025-01-01 2025-12-31".

## `expansion` (type: `string`):

How many Autocomplete lookups per seed. "basic" = the seed itself; "questions" = also what/how/why/is/can/best + seed and seed + vs/for/near; "full" (default) = also seed + a ... z. Deeper = more ideas, slower. Price is the same.

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

true (default) = add Google Trends interest (average, latest, peak, direction) and top + rising related queries. false = Autocomplete ideas only (faster, cheaper).

## `compareTopSuggestions` (type: `integer`):

0-4. Compare the seed with this many top Autocomplete ideas on one shared Trends 0-100 scale, to see which variant people search most. Default 0 (off). Adds 2 Trends requests per seed.

## `maxKeywordsPerSeed` (type: `integer`):

Cap on the merged keyword list per seed (5-500). Default 100. Lower it to keep agent context small; Trends queries are always kept.

## `outputMode` (type: `string`):

"compact" (default) = one result per seed with a summary and a nested keyword list. "flat" = one dataset row per keyword with the same field names, for CSV. Price is the same.

## `questionPrefixes` (type: `array`):

Optional. Replaces the built-in question words put before the seed. Example: \["how to", "what is", "best"]. Built-in lists exist for en, ro, de, fr, es, it, pt, nl, pl.

## `modifierSuffixes` (type: `array`):

Optional. Replaces the built-in words put after the seed. Example: \["vs", "for", "near me", "price"].

## `autocompleteDelaySecs` (type: `integer`):

Extra pause between Autocomplete lookups in seconds, 0-10. Default 0 (a built-in ~0.3 s polite pause always applies).

## `delayBetweenRequestsSecs` (type: `integer`):

Pause between Google Trends requests in seconds, 0-30. Default 1. Raise it if you see many retries in the log.

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

Retries on rate limits or network errors, 0-10. Default 3. Each retry uses a new session (and a new proxy IP).

## `requestTimeoutSecs` (type: `integer`):

Timeout per HTTP request in seconds, 5-120. Default 30.

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

Default {"useApifyProxy": true} (recommended: Google rate-limits busy IPs and retries rotate the IP). If the proxy is refused, the run continues without it.

## Actor input object example

```json
{
  "keywords": [
    "electric bike"
  ],
  "country": "US",
  "language": "en",
  "timeRange": "today 12-m",
  "expansion": "full",
  "includeTrends": true,
  "compareTopSuggestions": 0,
  "maxKeywordsPerSeed": 100,
  "outputMode": "compact",
  "autocompleteDelaySecs": 0,
  "delayBetweenRequestsSecs": 1,
  "maxRetries": 3,
  "requestTimeoutSecs": 30,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `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": [
        "electric bike"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("cleandata-labs/seo-keyword-research-for-agents").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": ["electric bike"],
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("cleandata-labs/seo-keyword-research-for-agents").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": [
    "electric bike"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call cleandata-labs/seo-keyword-research-for-agents --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,cleandata-labs/seo-keyword-research-for-agents"
        }
    }
}
```

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/nBqIdEmVijKYMrcvU/builds/IBYQyKJbJhxesrJH0/openapi.json