# Google Autocomplete Suggestions API (`khadinakbar/google-autocomplete-api`) Actor

Get current Google Search autocomplete suggestions for bounded keyword batches, optional A-Z expansion, and a selected language and country. Returns one structured, provenance-rich record per lookup with stable arrays for automation and AI agents.

- **URL**: https://apify.com/khadinakbar/google-autocomplete-api.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** SEO tools, MCP servers, Automation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 autocomplete lookups

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?

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 Suggestions API

Get current Google Search autocomplete predictions for a bounded list of seed queries. This Actor is for SEO teams, content researchers, and AI agents that need clean, locale-aware suggestion snapshots for keyword discovery alongside search-volume metrics and Google search-result research.

### Best fit for this Actor

Use it when you need the words Google currently predicts after a phrase, including optional prefix or suffix character expansion. Each completed lookup becomes one small JSON record with the exact query, ordered suggestions, selected language and country, source URL, and collection time. It works as a focused suggestions workflow, while keyword volumes, rankings, paid ads metrics, and SERP results each benefit from their own dedicated data source.

Google describes autocomplete as predictions derived from common searches and web patterns, which also vary with language, location, and live interest. Treat each record as a timestamped research signal rather than a factual statement or a popularity score.

### From seed list to content brief

A content strategist starts with `project management software`, runs the seed in `US` English, and exports the returned long-tail suggestions. With suffix expansion enabled, the strategist gets a wider but explicitly capped set of live query variants. The team clusters the `suggestions` array, keeps `sourceUrl` and `collectedAt` for provenance, then chooses topics only after combining this signal with its own audience and volume research.

### Quick start input

```json
{
  "queries": ["project management software", "best running shoes"],
  "language": "en",
  "country": "US",
  "expansionMode": "none",
  "maxLookups": 100
}
```

For a deliberately bounded long-tail pass, add `"expansionMode": "suffix"`. The Actor will fetch the original seed plus suffix variants, but will stop exactly at `maxLookups` rather than creating an open-ended run.

### Input reference

| Field | Type | What it controls |
| --- | --- | --- |
| `queries` | string\[] | 1–50 seed phrases, each up to 120 characters. Exact repeated phrases are deduplicated. |
| `language` | string | BCP 47-style suggestion-language hint such as `en`, `es`, or `pt-BR`; defaults to `en`. |
| `country` | string | Two-letter country hint such as `US`, `GB`, or `PK`; defaults to `US`. |
| `expansionMode` | enum | `none`, `prefix`, `suffix`, or `both`; expansion requests additional query variants. |
| `alphabet` | string | Unique letters/digits used for expansion; defaults to `abcdefghijklmnopqrstuvwxyz`. |
| `maxLookups` | integer | A 1–500 hard cap over all original and expanded lookups; defaults to 100. |

### What data you receive

One dataset item is one completed Google autocomplete lookup, even if the live response contains an empty suggestion array. The stable array format avoids sparse `suggestion_01` / `suggestion_02` fields and is easier to pass into clustering, spreadsheets, and AI workflows.

| Field | Meaning |
| --- | --- |
| `seedQuery` | Original seed from your input. |
| `query` and `expansion` | Exact lookup phrase and whether it is a seed, prefix, or suffix variant. |
| `suggestions` and `suggestionCount` | Ordered, de-duplicated current predictions and their count. |
| `language` and `country` | Context hints sent with the lookup; not a geographic guarantee. |
| `sourceUrl` and `collectedAt` | Replayable public endpoint URL and UTC collection timestamp. |

```json
{
  "seedQuery": "best running shoes",
  "query": "best running shoes",
  "expansion": "seed",
  "language": "en",
  "country": "US",
  "suggestions": [
    "best running shoes for men",
    "best running shoes for women"
  ],
  "suggestionCount": 2,
  "sourceUrl": "https://suggestqueries.google.com/complete/search?client=firefox&hl=en&gl=US&q=best+running+shoes",
  "collectedAt": "2026-08-24T10:00:00.000Z",
  "provider": "Google Search autocomplete"
}
```

### Terminal outcomes

Read `OUTPUT` or `RUN_SUMMARY` before using the dataset downstream. `COMPLETE` means every planned lookup persisted; `PARTIAL` preserves completed records and identifies collection issues or a cost-cap stop; `VALID_EMPTY` means valid lookups returned no predictions; `INVALID_INPUT` explains which bounded input to correct; and `UPSTREAM_FAILED` clearly reports an unavailable lookup path. The terminal record gives downstream workflows a visible outcome instead of an ambiguous empty result.

### Use through the API

```bash
curl "https://api.apify.com/v2/acts/khadinakbar~google-autocomplete-api/runs?token=$APIFY_TOKEN" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"queries":["project management software"],"language":"en","country":"US","maxLookups":1}'
```

After the run, retrieve the default dataset and read `OUTPUT` plus `RUN_SUMMARY`. Preserve `sourceUrl` and `collectedAt` when a later workflow needs to distinguish an older suggestion snapshot from a current one.

### Use with AI agents through Apify MCP

> Find current English Google autocomplete predictions for `project management software` in the United States. Use no A-Z expansion and one lookup. Return the suggestions with their source URL and collection time, label them as autocomplete predictions rather than search volume, and read the terminal outcome before answering.

This Actor is a bounded, read-only query-suggestion tool. Use `maxLookups` to budget calls before an agent expands a seed list. It returns query snapshots with a clear complementary role next to semantic analysis, keyword difficulty, ranking reports, and Google-result collection.

### Pricing

| Event | Price | When charged |
| --- | ---: | --- |
| Actor start | $0.00005 | Once when a run starts. |
| Autocomplete lookup | $0.005 | After one lookup snapshot is successfully persisted, including a valid empty suggestion list. |

This Actor uses Pay per event plus Apify platform usage. A default one-lookup run has up to $0.00505 in events, plus platform usage. `maxLookups` caps the lookup events at `maxLookups × $0.005`; an expanded run stays within that actor-level boundary. Check the live Pricing tab for the current event details and platform-usage configuration.

### Best results

- Submit clear phrase prefixes rather than full questions when you want the widest completion set.
- Select the language and country that match the audience you are researching, then retain them with each exported record.
- Use A-Z expansion only when the added coverage is worth the extra lookup count; start with a small `alphabet` and `maxLookups` for exploration.
- Compare snapshots collected on different dates carefully: Google says predictions can change with trends, language, and location.

### Builder's note

I designed the output as query-level and array-based after inspecting the live response shape. A fixed `suggestion_01` layout looks tidy in a spreadsheet yet loses ordering context whenever Google returns fewer predictions. This contract records exactly one response per billable lookup and pairs it with a source URL and timestamp so agent consumers receive a stable, compact entity.

### Focused standalone workflow

This Actor is designed as a focused standalone workflow for collecting current autocomplete snapshots. It works well before a content team clusters phrases, plans a brief, or passes selected terms into its preferred volume, rank, and SERP research tools.

### Responsible use

Use publicly available autocomplete data for lawful, authorized research and comply with Google’s terms and applicable laws. Treat predictions as contextual query-completion signals, and combine them with suitable evidence before making high-impact decisions.

# Actor input Schema

## `queries` (type: `array`):

One to 50 starting phrases sent to Google autocomplete, such as `project management software` or `best running shoes`. The Actor trims and de-duplicates exact repeated phrases, then optionally expands each seed. This is not a list of Google Search result URLs or a list of search-volume keywords.

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

Language hint sent to Google as a BCP 47-style code, for example `en`, `es`, or `pt-BR`. Defaults to `en`; Google can still vary predictions with the selected country and live trends. This is not the language of your Apify Console or an output-translation setting.

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

Two-letter ISO country hint sent to Google, for example `US`, `GB`, or `PK`. Defaults to `US` and changes the market context for predictions. This is not a guarantee that every prediction originates from that country.

## `expansionMode` (type: `string`):

Choose `none` for only the seed phrase, `suffix` for `seed a` through `seed z`, `prefix` for `a seed` through `z seed`, or `both` for both directions. Expansion discovers longer phrases but produces more billable autocomplete lookups. The maximum lookup cap always stops expansion predictably.

## `alphabet` (type: `string`):

Unique single characters used only when A-Z expansion is enabled, for example `abcdefghijklmnopqrstuvwxyz` or `abc123`. Defaults to the English alphabet and accepts at most 36 unique letters or digits. This is not a query prefix or suffix string.

## `maxLookups` (type: `integer`):

Hard maximum number of query variants fetched in this run. Defaults to 100 and caps at 500, including the original seeds, so expansion cannot create an unbounded bill. Each completed lookup persists one dataset record and costs $0.005 plus platform usage.

## Actor input object example

```json
{
  "queries": [
    "project management software",
    "best running shoes"
  ],
  "language": "en",
  "country": "US",
  "expansionMode": "none",
  "alphabet": "abcdefghijklmnopqrstuvwxyz",
  "maxLookups": 100
}
```

# Actor output Schema

## `suggestionSnapshots` (type: `string`):

One structured Google autocomplete response for every completed lookup query.

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

Detailed terminal outcome, lookup counts, failure details, and charges.

## `compactOutput` (type: `string`):

Stable terminal output for agents and automations.

## `lastRunSummary` (type: `string`):

Compatibility alias for the detailed terminal record.

# 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 = {
    "queries": [
        "project management software",
        "best running shoes"
    ],
    "language": "en",
    "country": "US",
    "expansionMode": "none",
    "alphabet": "abcdefghijklmnopqrstuvwxyz",
    "maxLookups": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/google-autocomplete-api").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 = {
    "queries": [
        "project management software",
        "best running shoes",
    ],
    "language": "en",
    "country": "US",
    "expansionMode": "none",
    "alphabet": "abcdefghijklmnopqrstuvwxyz",
    "maxLookups": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/google-autocomplete-api").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 '{
  "queries": [
    "project management software",
    "best running shoes"
  ],
  "language": "en",
  "country": "US",
  "expansionMode": "none",
  "alphabet": "abcdefghijklmnopqrstuvwxyz",
  "maxLookups": 100
}' |
apify call khadinakbar/google-autocomplete-api --silent --output-dataset

```

## MCP server setup

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

```

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/meCAriNdCHCRgcFoM/builds/FzoFtdyQMBeNhJ2hc/openapi.json