# 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
- **Features:** Limited permissions, Multi-tenant, Server interface
- **Stats:** 5 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 autocomplete lookups

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

### What is 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 with Apify platform usage included. A default one-lookup run has up to $0.00505 in events with Apify platform usage included. `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.

### Call over HTTP

This Actor also accepts authenticated GET and POST requests at its Actor server URL. Use your Apify bearer token. GET / returns readiness without source work or a result event, and GET /openapi.json returns the endpoint schema. Normal input-based runs, Dataset exports, existing limits and all paid options remain available.

POST /suggestions accepts the same queries, language, country, expansionMode, alphabet and maxLookups options. GET /suggestions?query=apify performs one seed request. Each completed query variant costs the existing $0.005, including a valid empty suggestion list; prefix/suffix expansions are separate lookup events.

Responses contain records and summary. HTTP results stay in the response and are not saved in the shared service Dataset or key-value store. Full rows are preserved; useful partial responses explicitly report failed and unprocessed work. No free-user quota was added or reduced.

Optional maxCostUsd bounds result-event charges for that request and is checked before source work. It does not enforce your Console-wide spending limit. Failed source work has no result event. If billing is rejected or uncertain, results are withheld with BILLING_UNCONFIRMED; do not retry automatically. Normal-run startup pricing is unchanged, and no second manual startup event is added to each HTTP request.

The service has finite retries/deadlines, two concurrent requests, 1 MiB request input, 512 KiB per source response and 2 MiB complete output. Oversized or long jobs should use normal batch runs. Paid-pool platform usage is deducted from developer payout; Apify covers free-pool run-attributed platform usage.

Normal-run startup events retain Apify’s selected-memory scaling; the default 256 MiB run has one start event.

# Changelog

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

# 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 with platform usage included.

## 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/kJCNC2N8G3nQZBIbB/openapi.json