Google Autocomplete API | Search & Place Suggestions for Agents

Get the autocomplete suggestions Google shows as you type, for any query, as clean structured JSON. Pass one or many partial queries and get back the ranked suggestion list for each. For location and place queries, these act as fast place suggestions you can pipe straight into a Maps or Places lookup. It is the lightweight front-end for query expansion, keyword research, and resolving partial searches before a heavier call.

What you get

One row per suggestion:

• query: the input query the suggestion belongs to
• position: the rank of the suggestion (1 is the top suggestion)
• value: the suggested query text

Use cases

• Resolve a partial place query into suggestions, then feed a chosen one into a Google Maps Places API
• Expand a seed keyword into the real phrases people search (SEO and PPC)
• Power a type-ahead box with Google's own suggestions
• Give an AI agent the likely full queries behind a vague user request
• Mine "near me", "open now", and long-tail variants for a location term

Input

Field	Type	Description
queries	array of strings	One or more partial queries, e.g. coffee near. Each is completed independently. Required.
gl	string	Optional two-letter country code, e.g. us, gb, de. Default us.
hl	string	Optional two-letter language code, e.g. en, es, de. Default en.

Example input

{
  "queries": ["coffee near", "best pizza in"],
  "gl": "us",
  "hl": "en"
}

Sample output

{
  "result_type": "suggestion",
  "query": "coffee near",
  "position": 1,
  "value": "coffee near me"
}

Each query typically returns about ten suggestions, ranked from most to least likely.

Pricing

Pay-per-result: a flat $0.002 per suggestion returned. No setup fee, no per-run fee, no monthly minimum. You only pay for the suggestions you receive.

How to get started

1. Open Google Autocomplete API on the Apify Store.
2. Enter one or more partial queries.
3. Optionally set gl / hl, then run the Actor.
4. Export the dataset as JSON, CSV, or Excel, or pull it from the API.

Prefer code? See johnvc's GitHub for setup guides and code examples.

Run from the API

curl -X POST "https://api.apify.com/v2/acts/johnvc~google-autocomplete-api/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["coffee near"],"gl":"us","hl":"en"}'

🔌 Use this API from Claude (MCP)

This Actor is compatible with the Model Context Protocol (MCP), so AI agents can call it as a tool. Add it through the hosted Apify MCP server using this Actor-specific URL:

https://mcp.apify.com/?tools=actors,docs,johnvc/google-autocomplete-api

If you run agents from Claude Code (free trial) or Claude Cowork (free trial), add the Apify MCP server and ask it to "autocomplete 'coffee near' and pick the best place query."

Setup walkthrough:

Apify MCP integration docs: https://docs.apify.com/platform/integrations/mcp

MCP setup, step by step

Visual setup guides for each client (source and more assets: ApifyPublicData on GitHub):

Claude Cowork Desktop (free trial)

Claude Code (free trial)

Claude (website)

Cursor

ChatGPT

FAQ

Does it return place IDs? No. It returns the suggested query text. For full place records (place ID, address, rating, coordinates), pipe a chosen suggestion into the Google Maps Places API.

How many suggestions per query? Usually about ten, the same set Google shows in its type-ahead box.

Can I autocomplete many queries at once? Yes. Pass multiple queries; each is completed independently and tagged with its source query.

Can I localize suggestions? Yes. Set gl (country) and hl (language) to localize the suggestions.

Last Updated: 2026.06.14