# Google Search Autocomplete Scraper — Query Suggestions (`sian.agency/google-search-autocomplete-scraper`) Actor

Get Google Search autocomplete suggestions for one query. Export the complete suggestion list, text highlights and available entity details in JSON. Each completed search is billed once, including searches with zero suggestions. Includes a processing report.

- **URL**: https://apify.com/sian.agency/google-search-autocomplete-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** Marketing, Business, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $70.72 / 1,000 completed autocomplete search records

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 — Search Suggestions 🔎

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Google Search Scraper](https://img.shields.io/badge/Store-Google%20Search%20Scraper-1AE392)](https://apify.com/sian.agency/google-serp-scraper?fpr=sian) [![Google Maps Photos Scraper](https://img.shields.io/badge/Store-Google%20Maps%20Photos%20Scraper-1AE392)](https://apify.com/sian.agency/google-maps-photos-scraper?fpr=sian) [![Local Business Data Scraper](https://img.shields.io/badge/Store-Local%20Business%20Data%20Scraper-1AE392)](https://apify.com/sian.agency/local-business-data-scraper?fpr=sian)

#### 💡 One search returns the complete suggestion list

##### Google Search autocomplete data for SEO consultants, editors and researchers

### 🔎 What is the Google Search Autocomplete Scraper — and when should you use it?

The **Google Search Autocomplete Scraper** turns complete Google Search suggestion lists for one seed query into clean, structured rows you can filter, export and feed straight into a spreadsheet, database or AI agent. No account, no portal API key, no browser automation to maintain.

**Use it when you need:** you need autocomplete phrases, highlights and available entity details with explicit search context.

**Use something else when:** you need ordinary web search results or organic page rankings. Use [Google Search Scraper](https://apify.com/sian.agency/google-serp-scraper?fpr=sian) for keyword-based organic web results. This actor returns suggestions only; it does not measure search volume or expand multiple seeds.

### 🤖 Use with AI agents

Already connected to the [Apify MCP server](https://mcp.apify.com)? Just ask for this Actor by name: sian.agency/google-search-autocomplete-scraper

**Your agent can pay for its own runs.** This Actor is eligible for [agentic payments](https://docs.apify.com/platform/actors/publishing/monetize), so an agent can discover it, run it and settle the bill over [x402](https://www.x402.org/) (USDC on Base) or [Skyfire](https://www.skyfire.xyz/) — without an Apify account or API token of its own. One completed search is charged once, including valid zero-suggestion searches. Failed retrievals have no completed-search charge. A separate run-start fee applies.

Otherwise copy this prompt into Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
I want a complete suggestion list for my seed phrase using the Apify Actor `sian.agency/google-search-autocomplete-scraper`.

Use it when I need: you need autocomplete phrases, highlights and available entity details with explicit search context.

Don't use it when: you need ordinary web search results or organic page rankings — use google-serp-scraper instead.

How to call it: set operation to autocomplete, supply query and choose language, region and device. Optionally set cursor. Read one complete search record and its suggestions array.

Start with this input:
{
  "operation": "autocomplete",
  "query": "adam",
  "language": "en",
  "region": "us",
  "device": "desktop"
}

Ask me which seed phrase and search context to use, then run the Actor and summarise the results as a table.
```

**Things you can ask your agent for:**

- *Collect autocomplete suggestions for this topic.*
- *Compare my seed phrase on US desktop and UK mobile in separate runs.*
- *Export the entity details returned for this partial name.*

Machine-readable API, MCP config and OpenAPI definition for this Actor are published at [apify.com/sian.agency/google-search-autocomplete-scraper.md](https://apify.com/sian.agency/google-search-autocomplete-scraper.md).

### 📋 Overview

Google Search Autocomplete Scraper completes one seed query and saves its suggestions in a single structured record. It preserves text highlights and any entity names, descriptions or images returned with the suggestions.

Use it to inspect how a phrase is completed in the selected search context. The suggestion order does not establish search volume or organic rankings.

- ✅ **Complete lists**: Every returned suggestion is kept in the JSON array.
- 🌍 **Search context**: Choose English or Spanish and a US, UK or Spain region.
- 📱 **Device choice**: Compare desktop and mobile in separate runs.
- 🧾 **One billing unit**: Each completed search costs one event, including a valid empty search.
- 📄 **Run report**: Review suggestion text and processing charges in the included HTML report.

Verified examples cover US English desktop, UK English mobile and Spain Spanish desktop with a cursor setting. Suggestions depend on the query and may change between runs.

### ✨ Features

- 🔎 **One seed query per run**: Keep the search and its returned list together.
- 📝 **Text highlights**: Preserve the offsets and lengths returned for matching text.
- 🏷️ **Entity context**: Keep available names, descriptions and image arrays.
- 🌐 **Language selector**: Use English or Spanish search context.
- 🌍 **Region selector**: Choose the US, UK or Spain without typing country codes.
- ⌨️ **Cursor position**: Set a position inside the phrase or leave it at the end.
- 📦 **JSON exports**: Retain the nested data or use the text list in your own workflow.
- 📊 **Explicit empty results**: A completed search with zero suggestions remains a useful receipt.

### 🎬 Quick Start

Open the actor's Input tab and run the "adam" example. The dataset contains one completed-search record with the full suggestion array. Replace the seed phrase and context before researching your own topic.

```bash
curl --request POST \
  'https://api.apify.com/v2/acts/sian.agency~google-search-autocomplete-scraper/runs?token=YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"operation":"autocomplete","query":"adam","language":"en","region":"us","device":"desktop"}'
```

The request starts a run. Wait for completion, then open the dataset identified by that run's default dataset ID. An API input without a query is rejected before the search event; the platform run-start fee still applies.

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Enter a seed query

Supply one phrase containing 1–999 characters. The Console example is a prefill, not an API default.

#### Step 2: Select search context

Choose language, region and device. Optionally choose a cursor position from zero to the trimmed query length.

#### Step 3: Run and export

Check the current event prices and maximum charge, then start the actor. Download JSON to preserve nested highlights and entity images. The Output tab also links to the processing report.

Free Apify accounts can run searches from the Console or MCP. Direct API runs require a paying Apify account. A blocked API run performs no search and has no completed-search charge; the platform run-start fee still applies.

### 📥 Input Configuration

| Field | Type | Required | Description |
|---|---|---|---|
| `operation` | string | No | Complete one Google Search autocomplete lookup. One output record contains the complete suggestion list and applied search settings. A completed lookup with zero suggestions is still billable; a failed retrieval has no completed-search charge. |
| `query` | string | Yes | The seed phrase to complete, from 1 to 999 characters. Console prefill is an example; API callers must supply a query. Each run performs one search and bills it once when completed, even if no suggestions are returned. |
| `language` | string | No | Choose the search language. English and Spanish are supported in this focused version. Suggestion availability depends on the query and region. |
| `region` | string | No | Country context for the search. The supplied US example returns English suggestions. Compare regions in separate runs using the same seed phrase. |
| `device` | string | No | Select desktop or mobile search context. Results may vary between device types; this controls the suggestion request context rather than emulating a personal browsing session. |
| `cursor` | integer | No | Optional cursor position within the query, starting at zero. Omit it to place the cursor at the end. The value cannot exceed the query length. |

```json
{
  "operation": "autocomplete",
  "query": "adam",
  "language": "en",
  "region": "us",
  "device": "desktop"
}
```

This version accepts one seed query per run. It does not expand letters, recurse through suggestions or combine multiple queries. Those are separate research steps you can implement in your own workflow.

### 📤 Output

One output row represents one completed search. The full suggestions array is preserved even when optional entity fields are absent. A valid empty search has `complete=true`, `resultsCount=0` and `suggestions=[]`.

| Field | Type | Meaning |
|---|---|---|
| `query` | string | Input query |
| `language` | string | Language |
| `region` | string | Region |
| `device` | string | Device |
| `resultsCount` | integer | Suggestions returned |
| `complete` | boolean | Search completed |
| `suggestions` | array | Complete suggestions |
| `suggestionTexts` | array | Suggestion text list |
| `firstSuggestion` | string or null | First suggestion |
| `entityImage` | string or null | First entity image |
| `searchParameters` | object | Applied search parameters |
| `status` | string | Status |
| `errorMessage` | string or null | Reason |
| `_operation` | string | Operation |
| `_fetchedAt` | string | Retrieved at |

**Recorded example, shortened to one suggestion:**

```json
{
  "query": "adam",
  "language": "en",
  "region": "us",
  "device": "desktop",
  "resultsCount": 10,
  "complete": true,
  "suggestions": [
    {
      "query": "adam sandler",
      "highlights": [
        {
          "offset": 0,
          "length": 4
        }
      ],
      "entity_title": "Adam Sandler",
      "entity_subtitle": "American comedian and actor",
      "entity_image": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR8Jn5CuFZ7Z1o9mWWkHvMdSrIEwuc5xH8ZMNJfF4nkwqQ01NXSsqQy4yR5KA&s=10",
      "entity_images": [
        "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR8Jn5CuFZ7Z1o9mWWkHvMdSrIEwuc5xH8ZMNJfF4nkwqQ01NXSsqQy4yR5KA&s=10",
        "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQVA1QJvr88RQBu2iEgUDU7Z-TFnqpRUg_X5YlUfNCWoy-nBTRuICIUWMuHIgJC1EL5i5kx3_X1AIO6l_0EIM2dEMwVHmQl&s=10",
        "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcQ3ELQuL_KOuu9zEEyJJQsf0BIJqjQJlVX30lk8YN1rnq0gN0FzJ21W0TZYqCUBkzXma8xv_GMaXZrUQGDsQHROA0gV9Oc&s=10",
        "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSPUFKmSeEvxSH2a1bY8SJlyCDn5qx7VcB0yTXT7sEujtdMINEdZ21Nsz8VY18FuIH9QGB_D1s5eMYPi8gUjc2kd_wJseQ&s=10"
      ]
    }
  ],
  "suggestionTexts": [
    "adam sandler",
    "adam levine",
    "adam and eve",
    "adam sandler movies",
    "adam shulman",
    "adam driver",
    "adam rubin",
    "adam scott",
    "adam driver movies and tv shows",
    "adam levine age"
  ],
  "firstSuggestion": "adam sandler",
  "entityImage": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcR8Jn5CuFZ7Z1o9mWWkHvMdSrIEwuc5xH8ZMNJfF4nkwqQ01NXSsqQy4yR5KA&s=10",
  "searchParameters": {
    "query": "adam",
    "language": "en",
    "region": "us",
    "cursor_pointer": 4,
    "user_agent": "desktop"
  },
  "status": "success",
  "errorMessage": null,
  "_operation": "autocomplete"
}
```

The recorded search returned ten suggestions. Only the first suggestion object is displayed above; actual records retain every object and image. Plain suggestions may contain just query text and highlights. Error rows have `complete=false` and may omit result fields.

JSON retains nested arrays. CSV and Excel exports show the search-level columns; arrays may appear as serialized text. The HTML report presents suggestion text in a table.

### 💼 Use Cases & Examples

#### 1. SEO consultants collecting keyword ideas

**Input:** A seed phrase in the selected language and region.
**Output:** Its complete suggestion list and text highlights.
**Use:** Prepare candidate phrases for separate search-volume research.

#### 2. Editors preparing content briefs

**Input:** A topic or partial question.
**Output:** The completions returned for that wording.
**Use:** Review related questions and phrase choices before writing a brief.

#### 3. Marketers comparing regions

**Input:** The same seed in separate US, UK and Spain runs.
**Output:** Search receipts with explicit language, region and device fields.
**Use:** Compare wording without losing the context used for each search.

#### 4. Researchers examining entities

**Input:** A name or partial name, such as the supplied "adam" example.
**Output:** Available entity titles, descriptions and images alongside suggestion text.
**Use:** Distinguish names returned for the same partial phrase. Entity fields are optional.

#### 5. Product teams studying search context

**Input:** Separate desktop and mobile searches for the same phrase.
**Output:** Suggestion snapshots for each selected device context.
**Use:** Inspect differences before designing your own search experience.

#### 6. Analysts saving recurring snapshots

**Input:** A saved phrase and fixed context on an Apify schedule.
**Output:** Timestamped records with complete suggestion lists.
**Use:** Compare changes in your spreadsheet or database. The actor does not store a separate history service.

### 🔗 Integration Examples

#### JavaScript / Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });
const run = await client.actor('sian.agency/google-search-autocomplete-scraper').call({
  operation: 'autocomplete', query: 'adam', language: 'en', region: 'us', device: 'desktop',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]?.suggestions);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')
run = client.actor('sian.agency/google-search-autocomplete-scraper').call(run_input={
    'operation': 'autocomplete', 'query': 'adam', 'language': 'en',
    'region': 'us', 'device': 'desktop',
})
for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item.get('suggestions'))
```

#### cURL: retrieve the completed dataset

```bash
curl 'https://api.apify.com/v2/datasets/YOUR_DATASET_ID/items?format=json&clean=true&token=YOUR_TOKEN'
```

Use the run-start request in Quick Start first, then replace YOUR_DATASET_ID with that completed run's dataset ID.

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger:** Start from a schedule or your own list of topics.
2. **HTTP Request:** Run the actor once for each seed query.
3. **Process:** Wait for completion and retrieve the search receipt.
4. **Action:** Save the suggestion list in a spreadsheet, brief or database.

### 📊 Performance & Pricing

One completed search costs one **completed-search** event. Every suggestion in that response is included. A search returning zero suggestions has the same event charge. Failed retrievals do not incur that event, and each run has a separate run-start fee.

| Apify plan | Completed search | Run-start fee | One completed run |
|---|---:|---:|---:|
| FREE | $0.32144 | $0.02 | $0.34144 |
| BRONZE | $0.08036 | $0.005 | $0.08536 |
| SILVER | $0.07554 | $0.005 | $0.08054 |
| GOLD | $0.07072 | $0.005 | $0.07572 |

Enterprise users should check their live Apify event price before running. FREE names the Apify account plan; these events still have the listed prices. The complete search must fit the remaining billing budget before retrieval. Processing time varies; no completion time is guaranteed.

[Check current pricing before running](https://apify.com/sian.agency/google-search-autocomplete-scraper?fpr=sian).

### ❓ FAQ

**What is billed?**

One completed search, even when it returns no suggestions. Suggestions within that search do not add charges. A separate run-start fee applies.

**Does this return search volume or rankings?**

No. It returns autocomplete suggestions, highlights and available entity fields. Suggestion order is not a search-results rank.

**Can I run several seed queries together?**

This version accepts one query per run. Save separate inputs or schedule individual queries.

**Why are entity fields absent?**

Many suggestions are plain phrases. Entity names, descriptions and images appear only when returned for that suggestion.

**Which locales are supported?**

English and Spanish, with US, UK or Spain region context. Availability varies by query.

**Are zero suggestions a failure?**

No. A completed empty search has complete=true, resultsCount=0 and an empty suggestions array.

### 🐛 Troubleshooting

**Input rejected**

Supply a non-empty query. Use the language, region and device options shown on the form. A cursor value cannot exceed the trimmed phrase length.

**No suggestions returned**

Try a different phrase or supported context. A valid empty search is completed and billed once. It is distinct from a retrieval failure.

**Entity fields missing**

Many suggestions are plain text. Entity details are included only when returned for a suggestion; they are not inferred or filled from another search.

**Search stops before retrieval**

Read the report. Check your maximum charge, account allowance and available credits before starting another run.

**Temporarily unavailable**

Wait a few minutes and retry manually. A data request is not automatically retried, so a failed attempt does not silently start another search.

### ⚖️ Legal Disclaimer

Results can contain names and images relating to people. Use them for a legitimate purpose and follow applicable privacy rules and service terms. Consult qualified counsel for advice on your specific use.

Google is a trademark of Google LLC. SIÁN Agency is independent and is not affiliated with or endorsed by Google.

### 🤝 Support

Report reproducible problems through the [Issues tab](https://apify.com/sian.agency/google-search-autocomplete-scraper/issues). Include the input and run URL, with sensitive information removed.

- 🛠️ [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian)
- 📧 <apify@sian-agency.online>

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Changelog

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

# Actor input Schema

## `operation` (type: `string`):

Complete one Google Search autocomplete lookup. One output record contains the complete suggestion list and applied search settings. A completed lookup with zero suggestions is still billable; a failed retrieval has no completed-search charge.

## `query` (type: `string`):

The seed phrase to complete, from 1 to 999 characters. Console prefill is an example; API callers must supply a query. Each run performs one search and bills it once when completed, even if no suggestions are returned.

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

Choose the search language. English and Spanish are supported in this focused version. Suggestion availability depends on the query and region.

## `region` (type: `string`):

Country context for the search. The supplied US example returns English suggestions. Compare regions in separate runs using the same seed phrase.

## `device` (type: `string`):

Select desktop or mobile search context. Results may vary between device types; this controls the suggestion request context rather than emulating a personal browsing session.

## `cursor` (type: `integer`):

Optional cursor position within the query, starting at zero. Omit it to place the cursor at the end. The value cannot exceed the query length.

## Actor input object example

```json
{
  "operation": "autocomplete",
  "query": "adam",
  "language": "en",
  "region": "us",
  "device": "desktop"
}
```

# Actor output Schema

## `googleSearchSuggestionSearches` (type: `string`):

Autocomplete search receipts with complete suggestions and available entity details. Choose JSON to preserve nested highlights and image arrays.

## `scrapingSummary` (type: `string`):

HTML summary showing successful and failed results with key metrics

# 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 = {
    "operation": "autocomplete",
    "query": "adam",
    "language": "en",
    "region": "us",
    "device": "desktop"
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/google-search-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 = {
    "operation": "autocomplete",
    "query": "adam",
    "language": "en",
    "region": "us",
    "device": "desktop",
}

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/google-search-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 '{
  "operation": "autocomplete",
  "query": "adam",
  "language": "en",
  "region": "us",
  "device": "desktop"
}' |
apify call sian.agency/google-search-autocomplete-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,sian.agency/google-search-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/eCRAHCkFcgexpChQr/builds/5iY7FcG82qy6JHEbZ/openapi.json