# Google Autocomplete API: Keyword Suggestions, Questions (`actose/google-autocomplete`) Actor

Expand keywords into Google Search, YouTube or Shopping autocomplete suggestions: a-z alphabet soup, digits, questions, relevance, any language and country. No API key, no login. MCP-ready for Claude, Cursor, ChatGPT and AI agents. Pay per result, empty results free. $4 per 1,000 keywords

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

## Pricing

from $3.40 / 1,000 expanded keywords

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 Autocomplete API: Keyword Suggestions & Questions Scraper

**$4.00 per 1,000 expanded keywords** — one keyword in, every Google Autocomplete suggestion out (typically 100-400 long-tail phrases per keyword with the a-z alphabet soup). Pay per result, no monthly rental. Keywords with no suggestion, errors and blocked requests are free.

This Actor turns seed keywords into long-tail keyword ideas from **Google Search, YouTube or Google Shopping autocomplete**, in any language and country. It queries the public suggest endpoint (the same one your browser uses), so there is **no API key, no login and no browser**: fast, cheap and stable.

### What does it do?

For each seed keyword it sends:

- the keyword itself,
- **alphabet soup / star expansion**: `keyword a` … `keyword z` (Cyrillic or Greek letters for `ru`, `uk`, `bg`, `el`, or your own letters),
- optionally **digits** `keyword 0` … `keyword 9`,
- optionally **prefix letters** `a keyword` … `z keyword`,
- optionally **question words** in the chosen language (`how / what / why…`, `comment / pourquoi / quel…`, `wie / was / warum…`, Spanish, Italian, Portuguese, Dutch).

All suggestions are merged, de-duplicated (case and spacing insensitive) and returned as **one dataset item per keyword**, with the seed query that produced each suggestion, its position and Google's relevance score.

### How much does it cost?

| What | Price |
|---|---|
| One expanded keyword (event `keyword`) | **$0.004** |
| 1,000 expanded keywords | **$4.00** |
| Keyword with no suggestion, failed or blocked | **$0** |

Example: a 250-keyword content plan with alphabet soup = 250 × $0.004 = **$1.00**, usually 40,000+ unique long-tail ideas. The price is the same whatever expansions you enable (digits, prefixes, questions). Proxy and compute are included.

### Input

```json
{
  "keywords": ["seo audit", "running shoes"],
  "language": "en",
  "country": "us",
  "source": "web",
  "expandAlphabet": true,
  "expandDigits": false,
  "expandPrefix": false,
  "expandQuestions": true,
  "onlyNew": false
}
```

| Field | Description |
|---|---|
| `keywords` | Seed keywords (required). Duplicates are removed. |
| `language` | Google `hl` code: `en`, `fr`, `de`, `es`, `it`, `pt`, `nl`, `ru`, `ja`… |
| `country` | Google `gl` code: `us`, `gb`, `fr`, `de`, `ca`… Empty = no country bias. |
| `source` | `web` (Google Search), `youtube` or `shopping`. |
| `expandAlphabet` | `keyword a…z` (default on). |
| `expandDigits` | `keyword 0…9`. |
| `expandPrefix` | `a…z keyword`. |
| `expandQuestions` | Localized question words before the keyword. |
| `customLetters` | Your own characters instead of the default alphabet (e.g. `abcdeéè`, `あいうえお`). |
| `onlyNew` | Only suggestions not seen in previous runs (for schedules). |
| `residentialFallback` | Retry through residential proxies if Google rate-limits server IPs (default on, included in price). |
| `maxConcurrency` | Parallel queries per keyword (1-10, default 5). |

### Output

One item per keyword:

```json
{
  "keyword": "seo audit",
  "language": "en",
  "country": "us",
  "source": "web",
  "suggestionsCount": 212,
  "suggestions": ["seo audit", "seo audit tool", "seo audit checklist", "seo audit free", "seo audit ai", "..."],
  "questions": ["how to do an seo audit", "what is an seo audit", "..."],
  "suggestionDetails": [
    {"suggestion": "seo audit tool", "seed": "seo audit", "seedType": "base", "position": 1, "relevance": 1250, "suggestionType": "QUERY", "seedCount": 3},
    {"suggestion": "seo audit ai", "seed": "seo audit a", "seedType": "suffix", "position": 1, "relevance": 1250, "suggestionType": "QUERY", "seedCount": 1}
  ],
  "suggestionsText": "seo audit\nseo audit tool\nseo audit checklist\n...",
  "onlyNew": false,
  "totalSuggestionsFound": 212,
  "newSuggestionsCount": null,
  "seedsQueried": 40,
  "seedsFailed": 0,
  "scrapedAt": "2026-10-16T08:00:00+00:00"
}
```

- `seedType`: `base`, `suffix` (a-z), `digit`, `prefix`, `question`.
- `seedCount`: how many seed queries returned this suggestion — a good proxy for how "central" the phrase is.
- `suggestionsText`: plain text, one suggestion per line, ready to paste into an LLM prompt or a RAG chunk.

Export as JSON, CSV, Excel or HTML from the dataset. Two ready-made views:

- **Overview** (`?view=overview`): one row per keyword with its suggestion and question lists.
- **One row per suggestion** (`?view=suggestionList`): a flat table (keyword, suggestion, seed, seedType, position, relevance, seedCount), ideal for Google Sheets or a keyword-clustering tool. CSV link: `https://api.apify.com/v2/datasets/<datasetId>/items?view=suggestionList&format=csv`.

### Use cases

#### 1. SEO content plan for a niche site

**Who:** an SEO consultant building topic clusters for a B2B site.
**Input:**

```json
{"keywords": ["account based marketing", "abm software", "intent data"], "language": "en", "country": "us", "expandAlphabet": true, "expandQuestions": true}
```

**Output (excerpt):** `["account based marketing examples", "account based marketing vs demand gen", "what is account based marketing", "abm software for small business", ...]` — about 600 phrases for $0.012.
**Next:** paste `suggestionsText` into an LLM to cluster phrases into pillar pages and FAQs, or export CSV to a keyword tool for volumes.

#### 2. Weekly trend watch in Google Sheets

**Who:** a French e-commerce marketer selling e-bikes.
**Input (scheduled every Monday):**

```json
{"keywords": ["vélo électrique", "trottinette électrique"], "language": "fr", "country": "fr", "onlyNew": true}
```

**Output (excerpt):** `{"keyword": "vélo électrique", "newSuggestionsCount": 7, "suggestions": ["vélo électrique prime 2027", "vélo électrique pliant léger", ...]}`
**Next:** the Apify Google Sheets integration appends only the new phrases; the team writes product pages before competitors. Cost: 2 × $0.004 per week, and $0 for a week with nothing new.

#### 3. YouTube video ideas for a creator agency

**Who:** a content strategist planning 50 videos per month.
**Input:**

```json
{"keywords": ["notion tutorial", "obsidian", "second brain"], "source": "youtube", "language": "en", "country": "gb", "expandQuestions": true}
```

**Output (excerpt):** `["notion tutorial for students", "notion tutorial 2026", "how to use obsidian for beginners", ...]`
**Next:** n8n sends the list to an LLM that drafts titles, then to a Trello board.

#### 4. Marketplace listing keywords

**Who:** an Amazon/Shopify seller writing product titles.
**Input:** `{"keywords": ["yoga mat", "resistance bands"], "source": "shopping", "expandDigits": true}`
**Next:** use the most frequent `seedCount` phrases in titles and bullet points.

### API examples

**Python**

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("<USERNAME>/google-autocomplete").call(run_input={
    "keywords": ["seo audit", "running shoes"], "language": "en", "country": "us",
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["keyword"], item["suggestionsCount"], item["suggestions"][:5])
```

**JavaScript**

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: '<YOUR_APIFY_TOKEN>' });
const run = await client.actor('<USERNAME>/google-autocomplete').call({
    keywords: ['seo audit', 'running shoes'], language: 'en', country: 'us',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((i) => console.log(i.keyword, i.suggestionsCount));
```

**HTTP (one call, returns items)**

```
POST https://api.apify.com/v2/acts/<USERNAME>~google-autocomplete/run-sync-get-dataset-items?token=<TOKEN>
{"keywords": ["seo audit"], "language": "en", "country": "us"}
```

### Integrations (Make, Zapier, n8n, Google Sheets)

- **Make / Zapier:** use the Apify "Run Actor" module with the input above, then "Get dataset items" → Google Sheets "Add row" with `keyword` and `suggestionsText`.
- **n8n:** HTTP Request node on the `run-sync-get-dataset-items` URL → Split Out on `suggestions` → your LLM or database node.
- **Google Sheets:** Apify's native integration exports each run to a sheet; combine with a schedule and `onlyNew: true` for a weekly "new keywords" tab.
- **Webhooks:** get notified when a run finishes.

### Use with AI agents (MCP)

This Actor is available through the Apify MCP server, so Claude, Cursor, ChatGPT and other AI agents can call it as a tool: "find long-tail keywords and questions for *X* in French". The output is compact JSON plus `suggestionsText` (plain text), so agents can read it without extra parsing. Typical agent flow: call with 3-10 keywords → cluster `suggestions` → draft an outline per cluster.

### FAQ

**Do I need a Google API key or account?** No. The Actor uses Google's public autocomplete endpoint. No login, no cookies.

**Why one charge per keyword and not per suggestion?** You pay for the work you ask for: one seed keyword fully expanded = $0.004, whether it yields 50 or 400 suggestions.

**Is search volume included?** No. Google Autocomplete doesn't publish volumes. The `relevance` score and `seedCount` give a relative ranking; use a keyword planner for absolute volumes.

**Which languages work?** Any language Google supports. Question words are built in for en, fr, de, es, it, pt, nl (English is used for others). Cyrillic and Greek alphabets are automatic; use `customLetters` for others (e.g. Japanese kana).

**What happens when my budget (max charge) is reached?** The Actor stops cleanly; it never delivers unpaid results.

**What about rate limits?** The Actor spreads queries, retries, and switches to proxies when Google limits an IP. Failed queries are reported in `seedsFailed`; a keyword where every query failed is not charged.

### Limitations

- Google returns at most ~10-15 suggestions per query, so a keyword with only alphabet soup yields at most ~400 phrases (usually fewer after de-duplication).
- Suggestions are personalised and vary slightly over time and by location; results reflect a neutral, logged-out user.
- No search volume, CPC or difficulty.
- `shopping` source uses Google's shopping autocomplete; if Google returns web suggestions instead, they are still delivered.
- Very rare or nonsense keywords return nothing (free).

# Actor input Schema

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

Seed keywords to expand. Each keyword becomes one result (one charge) with all its unique Google Autocomplete suggestions. Duplicates are removed automatically.

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

Two-letter interface language code sent to Google, e.g. en, fr, de, es, it, pt, nl, ru, ja. It changes suggestions and the question words used.

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

Two-letter country code to localize suggestions, e.g. us, gb, fr, de, ca. Leave empty for no country bias.

## `source` (type: `string`):

Which Google autocomplete to query: Google Search (web), YouTube search or Google Shopping.

## `expandAlphabet` (type: `boolean`):

Query "keyword a", "keyword b" … "keyword z" (Cyrillic or Greek letters for ru, uk, bg, el). This is the classic star expansion: about 27 queries per keyword.

## `expandDigits` (type: `boolean`):

Also query "keyword 0" … "keyword 9" (years, sizes, models).

## `expandPrefix` (type: `boolean`):

Also query "a keyword" … "z keyword" to find words that come before your keyword.

## `expandQuestions` (type: `boolean`):

Also query question words in the chosen language (how/what/why in English, comment/pourquoi/quel in French, wie/was/warum in German…). Great for FAQ and People-Also-Ask style content.

## `customLetters` (type: `string`):

Replace the default alphabet with your own characters, e.g. "abcdeéèfg" or "あいうえお". Leave empty for the default alphabet of the language.

## `onlyNew` (type: `boolean`):

Return only suggestions not seen in previous runs for the same keyword, language, country and source (memory kept in the named key-value store "google-autocomplete-state"). A keyword with no new suggestion is skipped and not charged.

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

If Google rate-limits server IPs, retry through residential proxies. Included in the price, keep it on for reliability.

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

How many autocomplete queries run in parallel (1-10). Lower it if you see rate limits.

## Actor input object example

```json
{
  "keywords": [
    "seo audit",
    "running shoes"
  ],
  "language": "en",
  "country": "us",
  "source": "web",
  "expandAlphabet": true,
  "expandDigits": false,
  "expandPrefix": false,
  "expandQuestions": false,
  "onlyNew": false,
  "residentialFallback": true,
  "maxConcurrency": 5
}
```

# Actor output Schema

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

One row per expanded keyword with its suggestion and question lists.

## `suggestionList` (type: `string`):

Flat list: one row per suggestion with seed query, seed type, position and Google relevance score.

## `suggestionListCsv` (type: `string`):

Same flat list exported as CSV for Excel or Google Sheets.

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

Full dataset items with every field, including suggestionsText (one suggestion per line, LLM-ready).

# 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": [
        "seo audit",
        "running shoes"
    ],
    "language": "en",
    "country": "us"
};

// Run the Actor and wait for it to finish
const run = await client.actor("actose/google-autocomplete").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": [
        "seo audit",
        "running shoes",
    ],
    "language": "en",
    "country": "us",
}

# Run the Actor and wait for it to finish
run = client.actor("actose/google-autocomplete").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": [
    "seo audit",
    "running shoes"
  ],
  "language": "en",
  "country": "us"
}' |
apify call actose/google-autocomplete --silent --output-dataset

```

## MCP server setup

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

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/4IxnSxURzFloWsAeU/builds/GFZD9tB84dZvQ68JK/openapi.json