# Google Keyword Suggestions Scraper (`googleapi/google-keyword-suggestions-scraper`) Actor

Collect public Google Suggest autocomplete suggestions with seed context and optional source-backed web, video, question, and related-search results from Google Search pages.

- **URL**: https://apify.com/googleapi/google-keyword-suggestions-scraper.md
- **Developed by:** [Google API](https://apify.com/googleapi) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.99 / 1,000 results

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?

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

Find public Google autocomplete suggestions for one or more seed phrases. Choose how Google expands each seed, filter and limit the suggestions, and optionally add visible results from Google Search.

### Quick start

Enter a seed phrase and choose a country and language. For a small run, set the expansion mode to **exact** and limit the generated requests and dataset rows:

```json
{
  "keywords": ["python tutorial"],
  "mode": "exact",
  "country": "US",
  "language": "en",
  "maxPages": 1,
  "maxItems": 10
}
```

### Input

| Input | Description |
| --- | --- |
| **keywords** | Seed phrases to expand (up to 100). The aliases **queries**, **query**, and **searchQuery** are also accepted. |
| **mode** | **exact** or **all** requests the seed phrase. **questions**, **prepositions**, **comparisons**, and **alphabet** generate related phrase variations. |
| **country / language** | Google country (gl) and language (hl) settings. Use **ALL** for country to omit the country setting. |
| **minLength / maxLength** | Keep suggestions within a character-count range. |
| **containsKeyword** | Keep suggestions containing this text. Prefix it with **!** to exclude matches. |
| **maxItemsPerKeyword** | Maximum unique suggestions kept for each seed (default 200; maximum 500). |
| **page / maxPages** | Starting position and request limit in the generated expansion list for each seed. These control expansion requests, not Google Search result pages. |
| **maxItems** | Maximum dataset rows across all seeds (default 25; maximum 500). |
| **outputFormat** | **flat** returns one row per suggestion; **tree** returns one row per seed with its suggestions nested. |
| **includeSearchResults** | Add public Google Search results for eligible suggestions. Off by default. |
| **maxSearchResultRequests** | Maximum distinct Search pages to fetch when enrichment is enabled (default 10; maximum 50). Repeated suggestions reuse the same results. |
| **maxSearchResultsPerType** | Maximum web results, videos, People also ask questions, and related searches retained per Search page (default 10; maximum 50). |
| **maxSearchResponseBytes** | Maximum size of each optional Search page response (default 4 MB). |
| **renderJavaScript** | Allow an ordinary browser to render Search pages that need it. Applies only when Search enrichment is on; browser rendering requires at least 1024 MB. |
| **proxyConfiguration** | Optional Apify proxy settings for Suggest and Search requests. Use proxy groups available to your account. |
| **searchProxyConfiguration** | Optional separate proxy for Search enrichment. When enabled, it applies only to Search; Suggest continues to use proxyConfiguration. |

Google Suggest returns a suggestion set for each request rather than numbered result pages. Expansion modes can generate multiple requests per seed, so use **page** and **maxPages** to control how many are made.

### Output

The dataset contains the suggestion, its seed phrase, country and language, its position in Google's response, and any Google relevance or type metadata that Google returns. It also includes simple text comparisons such as character count, whitespace-separated tokens, punctuation, whether the seed appears in the suggestion, and seed-token overlap. These comparisons are calculated from the returned text; they are not Google search-volume or intent metrics.

In **flat** format, each suggestion is a dataset row. In **tree** format, each row represents a seed and contains a **suggestions** array.

When Search enrichment is enabled, a suggestion may also include a **searchResults** object with visible organic results, video cards, People also ask questions, and related searches. Answers, dates, snippets, and other details are included only when Google displays them. The Actor does not follow result links to collect destination pages.

```json
{
  "suggestion": "python tutorial for beginners",
  "seedKeyword": "python tutorial",
  "language": "en",
  "country": "US",
  "suggestionOrder": 1,
  "googleRelevance": null,
  "googleSuggestionType": null,
  "googleSuggestionSubtypes": null,
  "suggestionCharacterCount": 29,
  "suggestionTokenCount": 4,
  "suggestionTokens": ["python", "tutorial", "for", "beginners"],
  "containsSeedKeyword": true,
  "exactSeedMatch": false,
  "seedTokenOverlapTokens": ["python", "tutorial"],
  "seedTokenOverlapCount": 2,
  "seedTokenOverlapRatio": 1
}
```

Download the dataset from the Apify run page in JSON, CSV, Excel, and other supported formats. Run counts and access outcomes are available in the run's output.

### Limits

- Google may vary suggestions by country, language, time, and access policy.
- Expansion modes can make many requests. Start with a small number of seeds and a low maxPages value.
- The Actor collects public autocomplete suggestions and does not provide Ads search volume, CPC, competition, or trend history.
- The Actor does not bypass CAPTCHAs or other access boundaries.

### FAQ

#### Why did a run return no suggestions?

Google may limit requests or show an access boundary. Check the run log, then retry later with fewer seeds and a modest request delay.

#### What does tree output contain?

Tree output groups each seed with its returned suggestion objects in a single dataset row. Flat output places each suggestion in its own row.

#### Is this an official Google product?

No. This Actor is not affiliated with, endorsed by, or sponsored by Google. Use collected data in accordance with Google's applicable terms and policies.

### Privacy

The Actor sends seed phrases and the selected country and language settings to Google's public Suggest service. If Search enrichment is enabled, it also sends eligible suggestion phrases to Google Search. Avoid submitting sensitive terms.

# Actor input Schema

## `renderJavaScript` (type: `boolean`):

When optional Search enrichment is enabled, render a JavaScript or unrecognized result page once in ordinary Chrome using the same requested proxy. Boundaries stop extraction. Browser rendering requires at least 1024 MB; disable for HTTP-only runs.

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

One or more seed phrases. Use this field or a compatibility alias.

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

Compatibility alias for the keywords array.

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

Compatibility alias for one seed phrase.

## `searchQuery` (type: `string`):

Compatibility alias for one seed phrase.

## `mode` (type: `string`):

Generates additional public Suggest requests from each seed.

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

Two-letter Google gl country code, or ALL to omit gl.

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

Google hl language code used for the Suggest response.

## `maxItemsPerKeyword` (type: `integer`):

Maximum unique suggestions retained for each seed after deduplication and filters.

## `minLength` (type: `integer`):

Drop suggestions shorter than this many characters.

## `maxLength` (type: `integer`):

Drop suggestions longer than this many characters.

## `containsKeyword` (type: `string`):

Keep suggestions containing this text; prefix with ! to exclude matches.

## `includeSearchResults` (type: `boolean`):

Fetch one public Google Search results page for each eligible suggestion. Disabled by default because this adds external requests and runtime cost.

## `maxSearchResultRequests` (type: `integer`):

Global cap on distinct Google Search pages fetched for suggestion enrichment. Duplicate suggestions reuse the same fetched result data.

## `maxSearchResultsPerType` (type: `integer`):

Maximum retained organic results, videos, People also ask questions, and related searches from each Google Search page.

## `maxSearchResponseBytes` (type: `integer`):

Maximum bytes read from each optional Google Search results page.

## `outputFormat` (type: `string`):

Flat emits one dataset row per suggestion; tree emits one row per seed with source suggestion objects nested.

## `maxItems` (type: `integer`):

Global cap across all seeds. In flat mode each suggestion is a row; in tree mode each seed is a row.

## `page` (type: `integer`):

One-based offset into the generated expansion-query list for each seed. Google Suggest itself does not expose numbered result pages.

## `maxPages` (type: `integer`):

Maximum generated Suggest requests to make for each seed from the selected starting expansion request. Bound by the expansion mode.

## `requestDelayMs` (type: `integer`):

Polite delay in milliseconds between public Suggest requests and optional Google Search page requests.

## `timeoutMs` (type: `integer`):

Abort a public Suggest or optional Google Search request after this many milliseconds.

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

Bounded retries for transient Suggest or Google Search request failures. Access boundaries are not retried.

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

Upper bound for each response body.

## `searchProxyConfiguration` (type: `object`):

Default off: Search shares the main proxy. Explicitly enable this separate route for Search only; GOOGLE_SERP uses the documented HTTP-only, no-session protocol. Autocomplete stays on the main route. No automatic route switching or direct fallback.

## `proxyConfiguration` (type: `object`):

Applies to Suggest and optional Search HTTP requests. Use account-enabled groups or custom URLs. Residential routing requires account access. No silent direct fallback; omit or explicitly disable for direct access. JavaScript interstitials remain access boundaries.

## Actor input object example

```json
{
  "renderJavaScript": true,
  "keywords": [
    "python tutorial"
  ],
  "mode": "all",
  "country": "US",
  "language": "en",
  "maxItemsPerKeyword": 200,
  "includeSearchResults": false,
  "maxSearchResultRequests": 10,
  "maxSearchResultsPerType": 10,
  "maxSearchResponseBytes": 4000000,
  "outputFormat": "flat",
  "maxItems": 25,
  "page": 1,
  "maxPages": 40,
  "requestDelayMs": 200,
  "timeoutMs": 30000,
  "maxRetries": 2,
  "maxResponseBytes": 1000000,
  "searchProxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Public Google Suggest records.

## `output` (type: `string`):

Result and pagination counts kept outside public dataset rows.

## `runHealth` (type: `string`):

Access-boundary and request-failure tallies kept outside public dataset rows.

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

Operational counts and access outcomes kept outside public rows.

# 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": [
        "python tutorial"
    ],
    "mode": "all",
    "country": "US",
    "language": "en",
    "maxItemsPerKeyword": 200,
    "includeSearchResults": false,
    "maxSearchResultRequests": 10,
    "maxSearchResultsPerType": 10,
    "maxSearchResponseBytes": 4000000,
    "outputFormat": "flat",
    "maxItems": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("googleapi/google-keyword-suggestions-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": ["python tutorial"],
    "mode": "all",
    "country": "US",
    "language": "en",
    "maxItemsPerKeyword": 200,
    "includeSearchResults": False,
    "maxSearchResultRequests": 10,
    "maxSearchResultsPerType": 10,
    "maxSearchResponseBytes": 4000000,
    "outputFormat": "flat",
    "maxItems": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("googleapi/google-keyword-suggestions-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": [
    "python tutorial"
  ],
  "mode": "all",
  "country": "US",
  "language": "en",
  "maxItemsPerKeyword": 200,
  "includeSearchResults": false,
  "maxSearchResultRequests": 10,
  "maxSearchResultsPerType": 10,
  "maxSearchResponseBytes": 4000000,
  "outputFormat": "flat",
  "maxItems": 25
}' |
apify call googleapi/google-keyword-suggestions-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,googleapi/google-keyword-suggestions-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/5r4BDiUqfuXverzHW/builds/eFH9h179PF3CD0cgj/openapi.json