# Google Autocomplete Scraper: Keyword Suggestions (`automation-lab/google-autocomplete-scraper`) Actor

Scrape Google autocomplete (Google Suggest) keyword suggestions with Google's relevance score. Up to 15 per query, A-Z, question and number expansion, recursive depth, many countries and languages. Pay per query, not per suggestion. Export to JSON, CSV, Excel.

- **URL**: https://apify.com/automation-lab/google-autocomplete-scraper.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** SEO tools, Developer tools
- **Features:** Limited permissions, Multi-tenant, Server interface
- **Stats:** 871 total users, 300 monthly users, 99.8% runs succeeded, 2 bookmarks
- **User rating**: 4.85 out of 5 stars

## Pricing

from $0.65 / 1,000 keyword expandeds

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 Scraper

Scrape Google autocomplete suggestions at scale for SEO keyword research, content planning, and PPC campaign expansion. Turn a handful of seed keywords into hundreds of long-tail keyword ideas using Google's own search predictions — in seconds.

### 🔍 What does Google Autocomplete Scraper do?

**Google Autocomplete Scraper** extracts keyword suggestions directly from [Google's autocomplete API](https://google.com) — the same predictions that appear when you start typing in the search bar. Enter seed keywords and receive every phrase Google suggests (also known as Google Suggest), with Google's own relevance score, organized by depth, language, and country.

The scraper communicates with Google's public suggest endpoint via lightweight HTTP requests — **no browser required**. This makes it significantly faster and cheaper than Playwright-based alternatives, and it runs comfortably on just 256 MB of memory.

**Key capabilities:**

- Extract up to **15 autocomplete suggestions per Google query** — you pay per query, not per suggestion, so more suggestions cost nothing extra
- **Google's relevance score** and suggestion type on every result, so you can rank keyword ideas without a second tool
- **Recursive expansion** (depth 1–3): take each suggestion and fetch its own sub-suggestions to build deep keyword trees
- **Alphabet append**: query "keyword a", "keyword b", ... "keyword z" to unlock up to 27× more variations
- **Many countries and languages in one run** — set `countries` and `languages`, and every combination is queried
- **Optional run-wide deduplication** — keep each suggestion once and avoid paying to expand a repeat
- Keyword ideas only: website links and calculator answers from Google are filtered out, and the query itself is never returned as its own suggestion
- Exact query provenance and zero-based Google response position on every result
- Query-local deduplication: repeated values in one response are removed while overlaps across seeds and expansions stay attributable
- Export to JSON, CSV, Excel, or pipe results directly via API

Try it instantly: [automation-lab/google-autocomplete-scraper](https://apify.com/automation-lab/google-autocomplete-scraper) — no API key or login required.

### Who is it for? (Google Autocomplete Scraper users)

**SEO specialists and content strategists**

- Discover long-tail keywords with real user intent behind them
- Map the full keyword space around a topic before writing a content brief
- Identify questions and modifiers your competitors may have missed
- Track how autocomplete suggestions evolve as topics gain or lose momentum

**PPC managers and growth marketers**

- Expand Google Ads keyword lists with real search queries, not guesses
- Find negative keyword candidates by seeing what Google associates with your terms
- Research competitor brand terms and adjacent queries for targeting
- Build keyword clusters for ad group structuring

**Market researchers and product teams**

- Understand what consumers are actively searching for in your niche
- Identify emerging product categories or pain points before they hit mainstream tools
- Compare search behavior across countries and languages side by side
- Validate product names or feature ideas against actual search language

**Affiliate marketers and niche researchers**

- Find buyer-intent keyword variations for review and comparison content
- Discover low-competition long-tail keywords for new niche sites
- Research sub-niches and topic clusters for content roadmaps
- Run alphabet append on a niche term to exhaust all keyword angles quickly

### ✅ Why use Google Autocomplete Scraper?

- **Real search behavior, not historical estimates** — autocomplete reflects what users are typing right now, not what they searched last month
- **Pure HTTP — no browser overhead** — runs in under a second per keyword; no Playwright, no Chromium, no wasted compute
- **Recursive expansion built in** — go 1–3 levels deep to build keyword trees automatically
- **No API key or Google account needed** — works out of the box with zero setup
- **Fully localized** — get suggestions for any language and country combination; discover local intent unavailable in English-only tools
- **Alphabet append for maximum coverage** — one click to query all 26 letter suffixes, uncovering suggestions most SEO tools miss
- **Apify platform advantages** — scheduling, proxy rotation, API access, export to Google Sheets, Zapier, Make, and 5,000+ apps
- **Pay only for what you use** — no monthly subscription; run-start and per-keyword charges are tiered by Apify plan

### 📊 What data can you extract?

| Field | Type | Description |
|-------|------|-------------|
| `keyword` | string | The original seed keyword you provided |
| `query` | string | The exact direct, alphabet, prefix, or recursive query sent to Google |
| `suggestion` | string | The autocomplete suggestion returned by Google |
| `position` | integer | Zero-based order in Google's response. Numbers can skip where a website link or calculator answer was left out |
| `relevance` | integer | Google's own relevance score for this suggestion. Higher ranks higher |
| `suggestionType` | string | Google's type for this suggestion, usually `QUERY` |
| `depth` | integer | Expansion depth: 0 = direct suggestion, 1 = sub-suggestion, 2 = deeper |
| `parentKeyword` | string | The query one level above `query`: the seed for alphabet and prefix queries, the earlier query for deeper levels, and null for the seed's own direct query |
| `language` | string | Language code used for the query (e.g., `en`, `es`, `de`) |
| `country` | string | Country code used for the query (e.g., `us`, `gb`, `jp`) |
| `scrapedAt` | string | ISO 8601 timestamp of when the suggestion was extracted |

**Result counts by configuration:**

| Configuration | Approximate results per seed keyword |
|---------------|--------------------------------------|
| Depth 1 (default) | Up to 10 suggestions (15 with `maxSuggestionsPerKeyword: 15`) |
| Depth 2 | Up to 110 suggestions (10 + 10×10) |
| Depth 3 | Up to 1,110 suggestions |
| Depth 1 + alphabet append | Up to 270 suggestions (27 × 10) |
| Depth 2 + alphabet append | Up to 2,970 suggestions |

### 💰 How much does it cost to scrape Google autocomplete suggestions?

This actor uses **pay-per-event** pricing — you pay only for what you scrape. No monthly subscription. All platform costs are included.

| Apify plan | Run start | Per keyword expanded |
|---|---:|---:|
| Free | $0.005 | $0.001 |
| Bronze | $0.00475 | $0.0009 |
| Silver | $0.00425 | $0.0008 |
| Gold | $0.00375 | $0.00065 |
| Platinum | $0.003 | $0.0005 |
| Diamond | $0.0025 | $0.0004 |

From November 23, 2026 the price will be: run start at today's Bronze price on every plan; per keyword expanded at today's Bronze price on Free and Bronze, 10% below it on Silver, and 20% below it on Gold, Platinum and Diamond.

#### Calculated cost examples (not event unit prices)

| Task | Seed keywords | Queries fired | Cost (Free tier) |
|---|---|---|---|
| Quick idea check | 1 keyword, depth 1 | 1 | ~$0.006 |
| Standard research session | 5 keywords, depth 1 | 5 | ~$0.010 |
| Deep keyword tree | 1 keyword, depth 2 | up to 11 | ~$0.016 |
| Alphabet sweep | 1 keyword, depth 1 + alphabet | 27 | ~$0.032 |
| Full niche map | 5 keywords, depth 2 + alphabet | up to 1,485 | ~$1.49 |

**You pay per Google query, not per suggestion.** One query returns up to 15 suggestions, which works out to about $0.0001 per suggestion or less. A query that returns nothing, a query that fails, and a run with invalid input are not charged.

**Free plan value:** With Apify's $5 monthly credit, you can run approximately **4,900 keyword queries** — enough to build a thorough keyword map for a new niche or content site.

### 🚀 How to scrape Google autocomplete suggestions

1. Go to [Google Autocomplete Scraper](https://apify.com/automation-lab/google-autocomplete-scraper) on the Apify Store
2. Click **Try for free** — no account required for the first run
3. In the **Keywords** field, enter one or more seed keywords (e.g., `web scraping`, `python tutorial`)
4. Set **Language** and **Country** for localized results (default: English / United States)
5. Choose **Expansion Depth**: `1` for a quick look, `2` for a comprehensive keyword list, `3` for an exhaustive tree
6. Optionally enable **Append Alphabet** to query all 26 letter suffixes for maximum coverage
7. Click **Save & Start** — the run typically completes in under 30 seconds for small inputs
8. When finished, click **Export** to download your suggestions as JSON, CSV, or Excel

**Input example — quick keyword idea check:**

```json
{
    "keywords": ["content marketing"],
    "language": "en",
    "country": "us",
    "maxDepth": 1,
    "appendAlphabet": false
}
```

**Input example — full niche keyword map:**

```json
{
    "keywords": ["affiliate marketing", "passive income ideas"],
    "language": "en",
    "country": "us",
    "maxDepth": 2,
    "appendAlphabet": true,
    "maxSuggestionsPerKeyword": 10
}
```

**Input example — question and numeric intent discovery:**

```json
{
    "keywords": ["running shoes"],
    "expansionPatterns": ["questionPrefixes", "numbers"],
    "maxDepth": 1
}
```

This opt-in mode keeps the standard direct query and adds bounded prefix queries such as `how running shoes` and `5 running shoes`. Inputs that omit `expansionPatterns` behave exactly as before.

**Input example — international SEO research (Spanish, Mexico):**

```json
{
    "keywords": ["marketing digital", "herramientas seo"],
    "language": "es",
    "country": "mx",
    "maxDepth": 1,
    "appendAlphabet": false
}
```

### ⚙️ Input parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `keywords` | array | required | One or more seed keywords to expand. Each becomes a root query. |
| `language` | string | `"en"` | ISO 639-1 language code for suggestions. Examples: `en`, `es`, `de`, `fr`, `ja`, `pt-BR`, `zh`. |
| `country` | string | `"us"` | Two-letter ISO 3166-1 country code. Examples: `us`, `gb`, `de`, `fr`, `jp`, `br`. `UK` is treated as `gb`. A code that is not two letters, such as `USA`, stops the run with a clear message and no charge. |
| `languages` | string\[] | — | Optional. Several languages in one run. Overrides `language`. Each language is combined with each country. |
| `countries` | string\[] | — | Optional. Several countries in one run. Overrides `country`. Each country is combined with each language. |
| `maxDepth` | integer | `1` | How many levels deep to recursively expand suggestions. `1` = direct suggestions only. `2` = also expand each direct suggestion. `3` = one more level. Max: 3. |
| `maxSuggestionsPerKeyword` | integer | `10` | Maximum suggestions to save per query, 1 to 15. Google returns up to 15, and the price per query stays the same. |
| `appendAlphabet` | boolean | `false` | Also query "keyword a", "keyword b", ... "keyword z" to find additional variations. Multiplies query count by ~27× but significantly increases coverage. |
| `expansionPatterns` | string\[] | `[]` | Optional extra fan-out before each seed: `questionPrefixes` queries who/what/when/where/why/how/can/is/are/should, while `numbers` queries 0-9. Each added query uses one `keyword-expanded` event. |
| `deduplicateSuggestions` | boolean | `false` | Save each suggestion once per language and country across the run, and do not expand a repeat. Off by default, so every query that produced a suggestion stays visible. |
| `maxRequestRetries` | integer | `3` | Maximum retry attempts for failed HTTP requests. Increase if you see timeouts. |

### 📄 Output examples

**Depth 0 result (direct suggestion from seed keyword):**

```json
{
    "keyword": "web scraping",
    "query": "web scraping",
    "suggestion": "web scraping python",
    "position": 0,
    "relevance": 601,
    "suggestionType": "QUERY",
    "depth": 0,
    "parentKeyword": null,
    "language": "en",
    "country": "us",
    "scrapedAt": "2026-03-23T12:00:00.000Z"
}
```

**Depth 1 result (sub-suggestion — expanded from a depth-0 suggestion):**

```json
{
    "keyword": "web scraping",
    "query": "web scraping python",
    "suggestion": "web scraping python tutorial for beginners",
    "position": 2,
    "relevance": 521,
    "suggestionType": "QUERY",
    "depth": 1,
    "parentKeyword": "web scraping",
    "language": "en",
    "country": "us",
    "scrapedAt": "2026-03-23T12:00:05.000Z"
}
```

**International result (Spanish, Spain):**

```json
{
    "keyword": "marketing digital",
    "query": "marketing digital",
    "suggestion": "marketing digital para principiantes",
    "position": 0,
    "relevance": 601,
    "suggestionType": "QUERY",
    "depth": 0,
    "parentKeyword": null,
    "language": "es",
    "country": "es",
    "scrapedAt": "2026-03-23T12:01:00.000Z"
}
```

### 💡 Tips for best results

- **Start with depth 1** to quickly evaluate what Google associates with your seed keywords, then increase depth for long-tail research
- **Use alphabet append for exhaustive coverage** — it exposes suggestions that only appear when a letter suffix is added, often revealing the most specific long-tail phrases
- **Combine depth 2 + alphabet on a single focused seed keyword** for the most thorough keyword map of one topic (this produces 2,970+ suggestions)
- **Use specific seed keywords** — "best running shoes for flat feet" yields more actionable suggestions than "shoes"; the more specific, the more relevant the sub-suggestions
- **Try the same keyword in multiple languages** to discover international keyword gaps — suggestions often differ substantially between `en/us` and `en/gb`
- **Run on a schedule** (weekly or monthly) to track how autocomplete evolves as topics trend or fade — Apify Console makes it easy to set recurring runs
- **Filter depth 0 results first** — these are the most popular direct associations; use them to prioritize which branches to expand
- **Keep maxDepth at 1 for PPC campaigns** — depth-1 suggestions are the most commercially relevant and least noisy

### 🔗 Integrations

Google Autocomplete Scraper connects to your existing workflow tools via the Apify platform:

**Google Autocomplete Scraper → Google Sheets**
Set up a scheduled run to automatically push fresh keyword suggestions into a Google Sheets tab weekly. Use the built-in Google Sheets integration in Apify Console — no code needed. Your SEO team always has up-to-date keyword ideas without manual research.

**Google Autocomplete Scraper → Ahrefs or SEMrush**
Export the scraper's output as CSV and import it into Ahrefs' Keywords Explorer or SEMrush's Keyword Magic Tool. Use autocomplete-discovered keywords as the seed list for volume and difficulty analysis — this hybrid approach finds more keywords than either tool would alone.

**Google Autocomplete Scraper → Google Ads Editor**
Run the scraper with `appendAlphabet: true` on your core product terms to generate a comprehensive long-tail keyword list. Export as CSV and import directly into Google Ads Editor for campaign keyword expansion without manual brainstorming.

**Google Autocomplete Scraper → Zapier / Make**
Trigger the scraper via webhook whenever a new product or topic is added to your system. Route results automatically to Slack, Airtable, Notion, or your content management system. Build a "keyword on demand" pipeline that fires without manual intervention.

**Google Autocomplete Scraper → Slack alerts**
Schedule weekly keyword research runs and use Apify's webhook integration to post a summary of newly discovered suggestions to your team's Slack channel. Keep the whole team aware of emerging search trends in your niche.

**Google Autocomplete Scraper → Content calendars**
Feed keyword trees (depth 2) into your content planning tool via API. Each top-level suggestion becomes a pillar page topic; each sub-suggestion becomes a supporting cluster article. Build a data-driven content calendar in minutes.

### API usage

Run Google Autocomplete Scraper programmatically from your own applications or scripts.

#### Node.js

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

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });

const run = await client.actor('automation-lab/google-autocomplete-scraper').call({
    keywords: ['content marketing', 'email marketing'],
    language: 'en',
    country: 'us',
    maxDepth: 2,
    appendAlphabet: false,
    maxSuggestionsPerKeyword: 10,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Found ${items.length} keyword suggestions`);
items.forEach(item => {
    console.log(`[${item.query} #${item.position}] ${item.suggestion}`);
});
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient('YOUR_API_TOKEN')

run = client.actor('automation-lab/google-autocomplete-scraper').call(run_input={
    'keywords': ['content marketing', 'email marketing'],
    'language': 'en',
    'country': 'us',
    'maxDepth': 2,
    'appendAlphabet': False,
    'maxSuggestionsPerKeyword': 10,
})

items = client.dataset(run['defaultDatasetId']).list_items().items
print(f"Found {len(items)} keyword suggestions")
for item in items:
    print(f"[{item['query']} #{item['position']}] {item['suggestion']}")
```

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~google-autocomplete-scraper/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["content marketing"],
    "language": "en",
    "country": "us",
    "maxDepth": 1,
    "appendAlphabet": false
  }'
```

To retrieve the results after the run completes:

```bash
curl "https://api.apify.com/v2/datasets/RUN_DEFAULT_DATASET_ID/items?token=YOUR_API_TOKEN"
```

### 🤖 Use with AI agents via MCP

Google Autocomplete Scraper is available as a tool for AI assistants that support the [Model Context Protocol (MCP)](https://docs.apify.com/platform/integrations/mcp).

Add the Apify MCP server to your AI client — this gives you access to all Apify actors, including this one:

#### Setup for Claude Code

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=automation-lab/google-autocomplete-scraper"
```

#### Setup for Claude Desktop, Cursor, or VS Code

Add this to your MCP config file:

```json
{
    "mcpServers": {
        "apify": {
            "url": "https://mcp.apify.com?tools=automation-lab/google-autocomplete-scraper"
        }
    }
}
```

Your AI assistant will use OAuth to authenticate with your Apify account on first use.

#### Example prompts

Once connected, try asking your AI assistant:

- "Use automation-lab/google-autocomplete-scraper to find all keyword suggestions for 'project management software' in English with depth 2, then organize the results by topic cluster"
- "Get Google autocomplete suggestions for 'keto diet' and 'intermittent fasting' and identify which long-tail keywords appear for both — those are the highest-opportunity topics"
- "Run the Google autocomplete scraper with alphabet append on 'email marketing' to build a complete keyword map, then highlight the top 20 most specific long-tail suggestions"

Learn more in the [Apify MCP documentation](https://docs.apify.com/platform/integrations/mcp).

### ⚖️ Is it legal to scrape Google autocomplete suggestions?

Google Autocomplete Scraper accesses Google's public suggest API — the same endpoint your browser calls when you type in the search bar. No login, no account, no authentication is required. The suggestions returned are freely provided to every internet user.

Scraping publicly available data is generally considered lawful. The [US Ninth Circuit Court of Appeals (hiQ Labs v. LinkedIn, 2022)](https://en.wikipedia.org/wiki/HiQ_Labs_v._LinkedIn) affirmed that accessing publicly available web data does not violate the Computer Fraud and Abuse Act. Similar legal precedents apply in the EU and UK.

**Best practices:**

- Use autocomplete data only for legitimate keyword research, SEO analysis, and market research purposes
- Do not use suggestions to build spam databases or engage in manipulative search behavior
- Review [Google's Terms of Service](https://policies.google.com/terms) for the latest policy updates
- For datasets involving personal data, ensure compliance with GDPR, CCPA, and other applicable privacy regulations

For more on the legality of web scraping, see [Apify's web scraping legality guide](https://blog.apify.com/is-web-scraping-legal/).

### ❓ FAQ

**How many suggestions does Google return per keyword?**
Google returns up to 15 autocomplete suggestions per query, and this Actor saves 10 by default (set `maxSuggestionsPerKeyword` to 15 for all of them; the price stays the same). The actual number depends on the keyword and locale — very new or niche terms may return fewer. Use alphabet append or increase depth to find more variations for low-suggestion keywords.

**How fast does the scraper run?**
Very fast. Each keyword query is a simple HTTP request that resolves in under 200ms. A standard run with 5 seed keywords at depth 1 completes in under 5 seconds. Even a large alphabet-append run (270 queries) typically finishes in under 2 minutes.

**How does this compare to paid keyword tools like Ahrefs or SEMrush?**
Those tools show search volume and keyword difficulty, but their keyword databases are updated infrequently and miss the freshest long-tail terms. Google Autocomplete shows real-time search behavior that keyword tools haven't yet indexed. The best approach is to use both: use this scraper to discover keyword ideas, then import them into Ahrefs or SEMrush for volume data.

**Why am I getting fewer results than expected?**
Some keywords have fewer suggestions in Google's system — this is normal for very niche, misspelled, or brand-new terms. If you expect more results, try: (1) enabling alphabet append, (2) increasing maxDepth to 2, or (3) trying slight variations of your seed keyword. Also verify your language/country combination is correct — `language: "es"` with `country: "us"` returns Hispanic-US suggestions, which may differ from `country: "es"`.

**Will I see the seed keyword itself as a suggestion, or website links?**
No. The query itself, website links, and calculator answers are left out, because they are not keyword ideas and expanding them would waste paid queries.

**What does a run cost when nothing comes back?**
Nothing. The run start and query charges only apply once a query delivers suggestions. Queries that return no suggestions or fail after retries are never charged, and invalid input stops before any charge.

**What if requests fail or return errors?**
The scraper retries failed requests automatically with a rising delay. If you see failures despite retries, increase `maxRequestRetries` to 5–10. The run's final status tells you how many suggestions were saved, how many queries answered, and how many failed.

**Can I run the scraper on a schedule to track keyword trends over time?**
Yes. Use Apify Console's built-in scheduler to run the actor daily, weekly, or monthly with the same input. Each run stores results in a separate dataset. You can compare datasets over time to see which suggestions appear, disappear, or change in phrasing — a useful signal for emerging topics.

### 🔗 Other Google and SEO scrapers

- [Google Search Scraper](https://apify.com/automation-lab/google-search-scraper) — scrape organic SERP results, People Also Ask, and related searches from Google Search
- [Google Shopping Scraper](https://apify.com/automation-lab/google-shopping-scraper) — extract product listings, prices, and merchant data from Google Shopping
- [Google News Scraper](https://apify.com/automation-lab/google-news-scraper) — scrape Google News headlines, articles, and topic clusters
- [Google Scholar Scraper](https://apify.com/automation-lab/google-scholar-scraper) — extract academic papers, citations, and author profiles from Google Scholar
- [Google Trends Scraper](https://apify.com/automation-lab/google-trends-scraper) — track keyword popularity trends and breakout searches over time
- [Google Maps Scraper](https://apify.com/automation-lab/google-maps-scraper) — extract business listings, reviews, and contact info from Google Maps
- [DuckDuckGo Scraper](https://apify.com/automation-lab/duckduckgo-scraper) — scrape search results from DuckDuckGo for privacy-focused SERP research
- [Keyword Density Analyzer](https://apify.com/automation-lab/keyword-density-analyzer) — analyze keyword frequency and density across any web page for on-page SEO audits

### 🔐 Diagnostics and privacy

When a run fails, this Actor sends sanitized diagnostic input, the error, and the Actor, build and run IDs to our private GlitchTip service so we can repair it. Secret fields and URL query strings are removed, and reports are kept for 30 days.

### Server API: get one keyword's suggestions over HTTP

Google Autocomplete Scraper is also a Server Actor. Besides normal runs, it answers short HTTP requests directly, without starting a run for each keyword. Copy the server URL from the Actor's **Server** tab (do not build it from the Actor name) and authenticate with your Apify token. Use normal Actor runs for many keywords, several languages or countries, and deeper expansion (`maxDepth` above 1).

```bash
curl -sS "$SERVER_URL/suggestions?keyword=coffee%20maker" -H "Authorization: Bearer $APIFY_TOKEN"
curl -sS "$SERVER_URL/suggestions?keyword=kaffee&language=de&country=de&maxSuggestions=5" -H "Authorization: Bearer $APIFY_TOKEN"
curl -sS "$SERVER_URL/suggestions?keyword=running%20shoes&appendAlphabet=true&expansionPattern=questionPrefixes&deduplicate=true" -H "Authorization: Bearer $APIFY_TOKEN"
```

| Method and path | Input | Output and charge |
| --- | --- | --- |
| `GET /` | None | `ready: true`, the routes and limits; no scraping or charge |
| `GET /suggestions` | Query `keyword`: one seed keyword (up to 200 characters); optional `language` (such as `en`, `de` or `pt-BR`; default `en`), `country` (two letters such as `us` or `gb`; default `us`), `maxSuggestions` (1–15; default 10), `appendAlphabet` (`true` adds "keyword a" to "keyword z"), `expansionPattern` (repeat for `questionPrefixes` and `numbers`), `deduplicate` (`true` returns each suggestion once) | `{ok,count,results}` with one row per suggestion, the same record as a normal dataset item at depth 0; one keyword-expanded event per query that returned suggestions (1 for the keyword alone, up to 47 with every expansion); no start fee |

A keyword with no suggestions returns an error and is free. Each request has a 45-second deadline and a 1 MiB response cap, and one server works on at most eight requests at once. Nothing is cached. Errors use `{ "ok": false, "error": { "code": "...", "message": "...", "retryable": false } }`: 400 `INVALID_INPUT`; 402 spending limit; 404 `NO_SUGGESTIONS` or unknown route; 405 wrong method; 413 `RESPONSE_TOO_LARGE`; 502 `UPSTREAM_ERROR` or charging failure; 503 server busy or stopping; 504 `TIMEOUT`. Failed requests are free. Retry only when `retryable` is true. The Server tab shows the full OpenAPI description.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/google-autocomplete-scraper/changelog.md

# Actor input Schema

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

Enter one or more seed keywords to get Google autocomplete suggestions for.

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

Language for autocomplete suggestions (ISO 639-1 code). Examples: en, es, de, fr, ja, pt-BR. To query several languages at once, use Multiple languages.

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

Country for localized suggestions (two-letter ISO 3166-1 code, not USA; UK is treated as gb). Examples: us, gb, de, fr, jp. To query several countries at once, use Multiple countries.

## `languages` (type: `array`):

Optional. Query several languages in one run, for example en, de, fr. Overrides Language. Every language is combined with every country, and each combination is its own set of queries.

## `countries` (type: `array`):

Optional. Query several countries in one run, for example us, gb, de. Overrides Country. Every country is combined with every language, and each combination is its own set of queries.

## `maxDepth` (type: `integer`):

Set how many levels deep to recursively expand suggestions. 1 = direct suggestions only, 2 = also expand each suggestion, 3 = one more level. Higher depth finds more long-tail keywords but takes longer.

## `maxSuggestionsPerKeyword` (type: `integer`):

Limit the number of suggestions saved per Google query. Google returns up to 15. The default is 10, and you pay per query, not per suggestion, so 15 costs the same.

## `appendAlphabet` (type: `boolean`):

Also query 'keyword a', 'keyword b', ... 'keyword z' for each seed keyword to discover more variations. Increases results significantly but also increases run time and cost.

## `expansionPatterns` (type: `array`):

Optionally add question prefixes (who, what, when, where, why, how, can, is, are, should) and/or numeric prefixes (0-9) before each seed keyword. Each added query uses one keyword-expanded event.

## `deduplicateSuggestions` (type: `boolean`):

Save each suggestion only once per language and country across the whole run, and do not expand a repeated suggestion again. Off by default, so every query that produced a suggestion stays visible.

## `maxRequestRetries` (type: `integer`):

Set the maximum number of retries for failed HTTP requests.

## Actor input object example

```json
{
  "keywords": [
    "web scraping"
  ],
  "language": "en",
  "country": "us",
  "maxDepth": 1,
  "maxSuggestionsPerKeyword": 15,
  "appendAlphabet": false,
  "deduplicateSuggestions": false,
  "maxRequestRetries": 3
}
```

# Actor output Schema

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

Google autocomplete suggestions collected by the run.

# 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": [
        "web scraping"
    ],
    "language": "en",
    "country": "us",
    "maxDepth": 1,
    "maxSuggestionsPerKeyword": 15,
    "appendAlphabet": false,
    "maxRequestRetries": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/google-autocomplete-scraper").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": ["web scraping"],
    "language": "en",
    "country": "us",
    "maxDepth": 1,
    "maxSuggestionsPerKeyword": 15,
    "appendAlphabet": False,
    "maxRequestRetries": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/google-autocomplete-scraper").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": [
    "web scraping"
  ],
  "language": "en",
  "country": "us",
  "maxDepth": 1,
  "maxSuggestionsPerKeyword": 15,
  "appendAlphabet": false,
  "maxRequestRetries": 3
}' |
apify call automation-lab/google-autocomplete-scraper --silent --output-dataset

```

## MCP server setup

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

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/7qfcupe7huVsrg6ug/builds/NnK3OsOomHReN7rSG/openapi.json