# Google Autocomplete Scraper (`cliqtomedia/google-autocomplete-scraper`) Actor

Collect live Google Search Autocomplete suggestions for seed keywords with language, country, expansion and run summary details.

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

## Pricing

$0.05 / 1,000 saved suggestions

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Google Autocomplete Scraper

Collect live Google Search Autocomplete suggestions for one or more seed
keywords. Choose the language, country and expansion modes, then get a clean
table with each suggestion, the Google query that produced it and a JSON run
summary.

Use this Actor for keyword research when you need live Google Autocomplete
suggestions. It gives you the suggestion text, the seed keyword, the Google
query, the country, the language and the rank returned by Google.

### What It Does

- accepts one or more seed keywords;
- supports Unicode keywords;
- sends direct Google Autocomplete requests for the selected language and
  country;
- can expand seeds with exact, alphabet, number and question queries;
- saves one row per unique useful suggestion;
- writes `RUN_SUMMARY` with counts, empty responses, failures and stop reasons.
- includes deterministic suggestion/request IDs and a redacted source URL for
  provenance.

### What It Does Not Do

- no Google Search result pages, ranks or page content;
- no search volume, CPC, competition or Google Ads Keyword Planner data;
- no AI keyword generation, clustering or scoring;
- no Google account, API key, browser automation, proxy routing or CAPTCHA
  bypass;
- no claim that results are complete or stable over time.

Google Autocomplete is dynamic. One run shows the ranked suggestions returned
for the exact queries, language, country and client used during that run.

### Input

Important fields:

- `keywords`: seed keywords, for example `coffee`;
- `language`: Google `hl` value, for example `en`;
- `country`: Google `gl` value, for example `us`;
- `expansionModes`: `exact`, `alphabet`, `numbers`, `questions`;
- `maxGeneratedQueries`, `maxResults`, `maxConcurrency` and `maxChargeUsd`:
  safety limits.

The default input is small and should finish quickly:

```json
{
  "keywords": ["coffee"],
  "language": "en",
  "country": "us",
  "client": "chrome",
  "expansionModes": ["exact"],
  "maxGeneratedQueries": 50,
  "maxResults": 100,
  "maxConcurrency": 4
}
```

### Output

Dataset rows include:

- `suggestion`;
- `seed`;
- `generatedQuery`;
- `expansionMode`;
- `language`;
- `country`;
- `client`;
- `googleRank`;
- `id`;
- safe metadata when Google returns it.

`RUN_SUMMARY` explains the run status and why any input or generated request
returned no row.

### Limits

- The Actor accepts up to 100 seed keywords.
- The Actor can plan up to 500 Google Autocomplete requests.
- The Actor can save up to 5,000 suggestion rows.
- The default input is small and cheap to run.

Set `maxChargeUsd` when you want the Actor to stop before the estimated charge
goes above your limit.

### Troubleshooting

- Empty Dataset with `RUN_SUMMARY.status` set to `succeeded`: Google returned a
  valid empty suggestion list for the executed query.
- `partial`: at least one input or Google request did not produce useful rows.
- `stopped`: the Actor reached a configured result, query, charge or time limit.
- `failed`: the run failed before useful suggestions could be saved.

### Disclaimer

This Actor is not affiliated with, endorsed by, or sponsored by Google. It uses
public Google Autocomplete responses and keeps traffic bounded by user-visible
limits.

# Actor input Schema

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

One or more keywords. The Actor trims spaces and keeps Unicode text such as cafe accents or Japanese keywords.

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

Google hl parameter, such as en, fr or ja.

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

Google gl parameter, such as us, fr or jp. This is not a promise of exact IP location.

## `client` (type: `string`):

Chrome usually returns more metadata. Firefox is kept as a simple fallback shape.

## `expansionModes` (type: `array`):

Exact uses each seed as-is. Alphabet, numbers and questions create extra visible Google requests.

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

Used only when questions expansion is enabled.

## `maxGeneratedQueries` (type: `integer`):

Stops expansion before too many Google Autocomplete requests are planned.

## `maxResults` (type: `integer`):

Stops writing new chargeable suggestion rows at this limit.

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

Number of Google requests allowed at the same time.

## `requestTimeoutMillis` (type: `integer`):

Timeout for one Google request in milliseconds.

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

Retries for transient network or server errors. Blocks and bad requests are not retried.

## `maxResponseBytes` (type: `integer`):

Stops parsing if one Google response is larger than this byte limit.

## `maxRunTimeSeconds` (type: `integer`):

Stops starting new requests after this many seconds.

## `includeRawMetadata` (type: `boolean`):

Adds safe per-suggestion metadata returned by the selected Google client when available.

## `maxChargeUsd` (type: `number`):

Optional safety stop based on the estimated per-suggestion charge before more rows are saved.

## Actor input object example

```json
{
  "keywords": [
    "coffee"
  ],
  "language": "en",
  "country": "us",
  "client": "chrome",
  "expansionModes": [
    "exact"
  ],
  "questionPrefixes": [
    "how",
    "what",
    "where",
    "why",
    "when",
    "which"
  ],
  "maxGeneratedQueries": 50,
  "maxResults": 100,
  "maxConcurrency": 4,
  "requestTimeoutMillis": 8000,
  "maxRetries": 1,
  "maxResponseBytes": 65536,
  "maxRunTimeSeconds": 240,
  "includeRawMetadata": true
}
```

# Actor output Schema

## `suggestions` (type: `string`):

Dataset table with one saved row per unique useful suggestion.

## `runSummary` (type: `string`):

JSON report with input, request, result, stop, warning and cost accounting.

# 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": [
        "coffee"
    ],
    "language": "en",
    "country": "us",
    "client": "chrome",
    "expansionModes": [
        "exact"
    ],
    "maxGeneratedQueries": 50,
    "maxResults": 100,
    "maxConcurrency": 4
};

// Run the Actor and wait for it to finish
const run = await client.actor("cliqtomedia/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": ["coffee"],
    "language": "en",
    "country": "us",
    "client": "chrome",
    "expansionModes": ["exact"],
    "maxGeneratedQueries": 50,
    "maxResults": 100,
    "maxConcurrency": 4,
}

# Run the Actor and wait for it to finish
run = client.actor("cliqtomedia/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": [
    "coffee"
  ],
  "language": "en",
  "country": "us",
  "client": "chrome",
  "expansionModes": [
    "exact"
  ],
  "maxGeneratedQueries": 50,
  "maxResults": 100,
  "maxConcurrency": 4
}' |
apify call cliqtomedia/google-autocomplete-scraper --silent --output-dataset

```

## MCP server setup

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