# Google Autocomplete API | Search & Place Suggestions for Agents (`johnvc/google-autocomplete-api`) Actor Get Google autocomplete suggestions for any query as structured JSON: the suggestions Google shows as you type. Resolve partial searches and surface place suggestions to feed into a Maps or Places lookup. Fast query and keyword expansion for SEO and AI agents. Pay per suggestion, MCP-ready. - **URL**: https://apify.com/johnvc/google-autocomplete-api.md - **Developed by:** [John](https://apify.com/johnvc) (community) - **Categories:** Developer tools, SEO tools, MCP servers - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $0.01 / 1,000 results 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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](https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3) - 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 ```json { "queries": ["coffee near", "best pizza in"], "gl": "us", "hl": "en" } ```` ### Sample output ```json { "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](https://apify.com/johnvc/google-autocomplete-api?fpr=9n7kx3). 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](https://github.com/johnisanerd/ApifyPublicData). ### Run from the API ```bash 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](https://claude.ai/referral/uIlpa7nPLg) (free trial) or [Claude Cowork](https://claude.ai/referral/uIlpa7nPLg) (free trial), add the Apify MCP server and ask it to "autocomplete 'coffee near' and pick the best place query." Setup walkthrough: https://www.youtube.com/watch?v=jREWahDGhJM 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](https://github.com/johnisanerd/ApifyPublicData)): **[Claude Cowork Desktop](https://claude.ai/referral/uIlpa7nPLg)** (free trial) ![Apify MCP install screenshot for the Cowork desktop app](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_desktop.png) **[Claude Code](https://claude.ai/referral/uIlpa7nPLg)** (free trial) ![Apify MCP install screenshot for the Code CLI](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_code.png) **Claude (website)** ![Install in Claude website](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_claude_ai.png) **Cursor** ![Install in Cursor](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_cursor.png) **ChatGPT** ![Install in ChatGPT](https://raw.githubusercontent.com/johnisanerd/ApifyPublicData/main/assets/guides/install_mcp_into_ChatGPT.png) ### 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](https://apify.com/johnvc/google-maps-places-api?fpr=9n7kx3). **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 # Actor input Schema ## `queries` (type: `array`): Provide one or more partial queries to autocomplete, for example 'coffee near' or 'best pizza in'. Each query is completed independently and billed per suggestion returned. ## `gl` (type: `string`): Set the two-letter country code for localization, for example 'us', 'gb', 'de'. Defaults to 'us'. ## `hl` (type: `string`): Set the two-letter interface language code, for example 'en', 'es', 'de'. Defaults to 'en'. ## Actor input object example ```json { "queries": [ "coffee near" ], "gl": "us", "hl": "en" } ``` # Actor output Schema ## `suggestions` (type: `string`): All suggestion rows stored in the default dataset, one item per suggestion. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "queries": [ "coffee near" ] }; // Run the Actor and wait for it to finish const run = await client.actor("johnvc/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "queries": ["coffee near"] } # Run the Actor and wait for it to finish run = client.actor("johnvc/google-autocomplete-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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": [ "coffee near" ] }' | apify call johnvc/google-autocomplete-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=johnvc/google-autocomplete-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Google Autocomplete API | Search & Place Suggestions for Agents", "description": "Get Google autocomplete suggestions for any query as structured JSON: the suggestions Google shows as you type. Resolve partial searches and surface place suggestions to feed into a Maps or Places lookup. Fast query and keyword expansion for SEO and AI agents. Pay per suggestion, MCP-ready.", "version": "0.0", "x-build-id": "ldUwUYiW8Nes98RQx" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/johnvc~google-autocomplete-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-johnvc-google-autocomplete-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/johnvc~google-autocomplete-api/runs": { "post": { "operationId": "runs-sync-johnvc-google-autocomplete-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/johnvc~google-autocomplete-api/run-sync": { "post": { "operationId": "run-sync-johnvc-google-autocomplete-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "queries" ], "properties": { "queries": { "title": "Queries", "minItems": 1, "type": "array", "description": "Provide one or more partial queries to autocomplete, for example 'coffee near' or 'best pizza in'. Each query is completed independently and billed per suggestion returned.", "items": { "type": "string" } }, "gl": { "title": "Country", "type": "string", "description": "Set the two-letter country code for localization, for example 'us', 'gb', 'de'. Defaults to 'us'.", "default": "us" }, "hl": { "title": "Language", "type": "string", "description": "Set the two-letter interface language code, for example 'en', 'es', 'de'. Defaults to 'en'.", "default": "en" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```