Use Google Autocomplete Keyword Expansion Scraper with Python

Expand seed keywords into long-tail suggestions using Google's autocomplete, with question-word, preposition, comparison, and A-to-Z expansion modes across any country and language.

1. Choose the data you need

Review the published README for supported collection modes, examples, and limits. The recipe below uses the current published input definition.

2. Prepare a source-based input

This JSON contains published prefills and required-field defaults. Review every value for your task before running it; it is not a promise of successful collection.

{
  "country": "US",
  "dedupeAcrossSeeds": false,
  "expansionDepth": "0",
  "includeIntent": false,
  "keywords": [
    "python tutorial"
  ],
  "language": "en",
  "maxItems": 3,
  "maxSuggestionsPerSeed": 3,
  "mode": "exact",
  "outputFormat": "flat",
  "source": "web"
}

Download input.example.json and save your reviewed copy as input.json.

Field	Type	Required	Description
`keywords`	array	required	One or more seeds. 1-3 word seeds return the most suggestions. Each seed is expanded according to `mode`.
`mode`	string	optional	How each seed is expanded. `all` runs every strategy; `exact` queries only the seed; `alphabet` adds a-z and 0-9 before and after; `questions` uses locale question words; `modifiers` adds prepositions and buyer-intent words; `related` adds trailing-space, wildcard, local, review and price variants.
`country`	string	optional	Google market used for the `gl` parameter. Changes ranking and local phrasing. 134 markets were verified against the live endpoint; the legacy `ALL` value maps to US.
`language`	string	optional	Language used for the `hl` parameter and for the locale-aware question and modifier words. 19 languages have native expansion vocabularies; the rest fall back to English modifiers.
`source`	string	optional	Which Google autocomplete surface to query: web, YouTube or Shopping. `all` runs all three and multiplies the request count.
`maxItems`	integer	optional	Hard cap on dataset records across all seeds and sources. Flat mode counts suggestions; tree mode counts one record per seed/source.
`maxSuggestionsPerSeed`	integer	optional	Cap on suggestions collected for one seed, applied after all expansion queries have run. Defaults to 2,000 when omitted (legacy maxItemsPerKeyword is honoured).
`minLength`	integer	optional	Drop suggestions shorter than this many characters.
`maxLength`	integer	optional	Drop suggestions longer than this many characters.
`containsKeyword`	string	optional	Keep only suggestions containing this substring (case-insensitive). Prefix with `!` to exclude matches instead.
`outputFormat`	string	optional	`flat` emits one row per suggestion. `tree` emits one row per seed and source with a nested suggestions array (the legacy shape).
`expansionDepth`	string	optional	Re-query the first 15 discovered suggestions to go one or two levels deeper. Off for the cheapest run.
`dedupeAcrossSeeds`	boolean	optional	Emit a phrase only once per run. Off keeps every seed complete; on removes overlaps between seeds.
`includeIntent`	boolean	optional	Add a deterministic intent tag (question, comparison, local, transactional, commercial, informational) where a language vocabulary matches.

3. Start an Actor run

Set APIFY_TOKEN in your environment. Python 3.10 or newer is sufficient; this recipe uses no third-party packages.

Execution may incur charges. Review current pricing on Apify. The request asks for a 120-second timeout and a charge limit; these settings are subject to Apify’s pricing and do not guarantee an all-inclusive spending cap.

import json
import os
import urllib.request

# Save the schema-derived example as input.json; review and edit it first.
with open("input.json", encoding="utf-8") as stream:
    actor_input = json.load(stream)

token = os.environ["APIFY_TOKEN"]
request = urllib.request.Request(
    "https://api.apify.com/v2/acts/l720olFLJbUgIME9n/runs?timeout=120&maxTotalChargeUsd=0.50",
    data=json.dumps(actor_input).encode("utf-8"),
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json"},
    method="POST",
)
# This starts a potentially billable run. Do not automatically retry this POST.
with urllib.request.urlopen(request, timeout=40) as response:
    run = json.load(response)["data"]
print("Run ID:", run["id"])
print("Status:", run["status"])
# Inspect and download results in Apify Console once the run succeeds.

4. Inspect the actual results

Open the run in Apify Console and wait for a successful completion. Use the published output schema to locate results and the dataset schema to understand declared views. Missing or optional record fields must not be treated as guaranteed values.

Keyword suggestions with seed, expansion type, position, locale, source URL, Google relevance and optional recursion depth.

Questions before you run

Which inputs are required?

The published required fields are keywords

What does this guide verify?

The fields, prefills, and schema links are rendered from the published build. This is a usage recipe, not a paid live extraction test. Source availability and collection results can vary.

What if the run request times out?

Check Apify Console before retrying. The first request may already have created a run. Do not automatically repeat a run-creation POST.

Open on Apify Full Actor reference

Generated from source build 9hAh7UqGFMaiIDlEq and its README and schemas. Source changes regenerate this guide; no third-party editorial claims are inferred.