Google Autocomplete API
Real-time search suggestions and multi-round SEO keyword expansion.
What is this API?
Serqo’s Google Autocomplete API provides programmatic access to Google's real-time search suggestions. Beyond basic single-query completions, it supports multi-round expansion strategies—including A-Z alphabet soup, question terms, prepositions, intent keywords, and recursive tree exploration—designed for keyword discovery and SEO research.
Common use cases
- Power real-time search bar dropdowns and instant query completions.
- Uncover long-tail keywords across 26 letters (A-Z) for content planning and SEO.
- Extract common user questions (
how,why,what) for FAQ and blog post outlines. - Analyze commercial intent and comparative search patterns (
vs,best,review). - Map recursive keyword topic clusters and search interest hierarchies.
Request example
POST https://api.serqo.io/v1/autocomplete
Both POST (JSON body) and GET (query string parameters) are supported on /v1/autocomplete and /v1/suggest.
Request headers
Create an API key and store it on your server. Send the API key in the x-api-key header.
| Header | Value | Description |
|---|---|---|
| Content-Type | application/json | JSON request body (for POST). |
| x-api-key | YOUR_API_KEY | API key used to authenticate the request. |
export SERP_API_KEY='YOUR_API_KEY'
curl https://api.serqo.io/v1/autocomplete \
-H "x-api-key: $SERP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"q": "nextjs",
"strategy": "alphabet",
"gl": "us",
"hl": "en"
}' Code examples
Use the same API key with a standard HTTP client. These examples require Node.js 22 or later, or Python 3.
const response = await fetch('https://api.serqo.io/v1/autocomplete', {
method: 'POST',
headers: {
'x-api-key': process.env.SERP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
q: 'nextjs',
strategy: 'alphabet',
gl: 'us',
hl: 'en',
}),
});
const result = await response.json();
if (!response.ok) {
console.error(response.status, result.requestId, result.error);
} else {
console.log(`Discovered ${result.meta.totalKeywords} keywords in ${result.meta.durationMs}ms`);
console.log(result.data.suggestions.slice(0, 10));
} import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen
payload = {
'q': 'nextjs',
'strategy': 'questions',
'gl': 'us',
'hl': 'en',
}
req = Request(
'https://api.serqo.io/v1/autocomplete',
data=json.dumps(payload).encode('utf-8'),
headers={
'x-api-key': os.environ['SERP_API_KEY'],
'Content-Type': 'application/json',
},
)
try:
with urlopen(req) as resp:
data = json.load(resp)
print(f"Total suggestions: {data['meta']['totalKeywords']}")
for item in data['data']['suggestions'][:5]:
print(f"- {item['keyword']} (relevance: {item['relevance']})")
except HTTPError as err:
print(err.code, json.load(err)) Parameters
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| q | string | Yes | — | Seed keyword. Maximum length: 300 characters. query is accepted as an alias. |
| strategy | string | No | normal | Expansion strategy: normal, alphabet, questions, prepositions, intent, seo_matrix, deep. |
| gl | string | No | us | Two-letter ISO country code. country is accepted as an alias. |
| hl | string | No | en | Interface language code. lang is accepted as an alias. |
| depth | integer | No | 1 | Recursive depth (1 to 3). Effective when strategy is deep. |
| limit | integer | No | — | Maximum number of suggestions to return (1 to 1000). |
| timeout | integer | No | 25000 | Global execution timeout in milliseconds (100 to 30000). |
| includeGroups | boolean | No | true | When true, groups categorized keywords in data.groups. |
| noCache | boolean | No | false | When true, bypasses server-side query cache. |
Expansion strategies
normal: Direct completion for the seed keyword. Returns 8 to 15 instant suggestions in ~200ms.alphabet: Dispatches 26 parallel suffix queries (q atoq z). Yields 150 to 220 distinct long-tail keywords.questions: Appends question pre-modifiers (how to,why does,what is). Ideal for FAQ creation.prepositions: Appends comparison and contextual connectors (vs,for,with).intent: Tests high-value purchase and transactional terms (best,buy,price,review).seo_matrix: Combined comprehensive matrix covering letters, questions, and commercial modifiers up to 40 rounds.deep: Multi-level tree exploration up to 3 tiers deep. Returns hierarchical parent-child clusters indata.tree.
Response
HTTP 200. A standard unified JSON response envelope:
{
"success": true,
"requestId": "ac_01jm9x48...",
"data": {
"seedQuery": "nextjs",
"suggestions": [
{
"keyword": "nextjs api routes",
"relevance": 1250,
"type": "QUERY",
"sourceType": "alphabet",
"group": "a",
"round": 1
},
{
"keyword": "nextjs authentication",
"relevance": 1200,
"type": "QUERY",
"sourceType": "alphabet",
"group": "a",
"round": 1
}
],
"groups": {
"a": [
{
"keyword": "nextjs api routes",
"relevance": 1250,
"type": "QUERY"
}
]
}
},
"meta": {
"strategy": "alphabet",
"country": "us",
"lang": "en",
"durationMs": 1824,
"totalKeywords": 178,
"rounds": 27,
"credits": 5,
"cache": "miss",
"partial": false
}
} Pricing and credits
Credits are deducted based on the complexity and dispatch rounds of the selected expansion strategy:
| Strategy | Sub-queries dispatched | Credits consumed | Use case |
|---|---|---|---|
| normal / direct | 1 round | 1 credit | Real-time search bar dropdowns |
| questions | 10 to 15 rounds | 3 credits | FAQ and blog content ideation |
| prepositions | 10 to 15 rounds | 3 credits | Comparative (vs, with) search terms |
| intent | 10 to 15 rounds | 3 credits | High-intent commercial queries (best, buy) |
| alphabet | 27 rounds (A-Z) | 5 credits | Complete 26-letter long-tail keyword discovery |
| seo_matrix | Up to 40 rounds | 8 credits | Full comprehensive SEO matrix expansion |
| deep | Hierarchical | depth=1: 1 creditdepth=2: 4 creditsdepth=3: 8 credits | Multi-level topic tree exploration |
- Cache hits are free: Identical queries served from the query cache consume 0 credits.
- No charge on failure: Failed requests and upstream timeouts never consume credits; reservations are automatically released.
- Upstream bundle discount: Multi-round strategies like
alphabet(5 credits) cost up to 80% less than dispatching 26 separate API searches. - Safe limits: Protected by a 25s deadline circuit breaker, 40-round cap, and client disconnection abort.
Errors and status codes
{
"success": false,
"requestId": "ac_01jm9x48...",
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Insufficient credits for this request",
"retryable": false
}
} | HTTP status | Error code | Meaning and resolution |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, invalid, or revoked API key. Pass a valid key in x-api-key. |
| 402 | INSUFFICIENT_CREDITS | Account balance is lower than the credits required for the requested strategy. Top up in the console. |
| 422 | INVALID_PARAM | A parameter is missing or out of valid bounds (e.g. unknown strategy, depth > 3). |
| 429 | QUOTA_EXCEEDED | Rate limit exceeded. Check retryAfterMs before sending the next request. |
| 500 | INTERNAL_ERROR | Internal server error. Reservations are automatically released without charge. |
Frequently asked questions
How does billing work for multi-round autocomplete strategies?
Multi-round strategies such as alphabet dispatch parallel sub-queries under a single API call, billed at a discounted flat rate (e.g. 5 credits for 26 letters) instead of charging for 26 separate searches. Upstream timeouts and failures automatically release reservations without charge.
Can I use the Google Autocomplete API for real-time search bar dropdowns?
Yes. Use the normal strategy for instant single-round completions with ~200ms response time. Both POST (JSON body) and GET (query parameters) are supported on /v1/autocomplete and /v1/suggest.