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.

HeaderValueDescription
Content-Typeapplication/jsonJSON request body (for POST).
x-api-keyYOUR_API_KEYAPI key used to authenticate the request.
bash
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.

JavaScript (Node.js)
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));
}
Python 3
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

FieldTypeRequiredDefaultDescription
qstringYes—Seed keyword. Maximum length: 300 characters. query is accepted as an alias.
strategystringNonormalExpansion strategy: normal, alphabet, questions, prepositions, intent, seo_matrix, deep.
glstringNousTwo-letter ISO country code. country is accepted as an alias.
hlstringNoenInterface language code. lang is accepted as an alias.
depthintegerNo1Recursive depth (1 to 3). Effective when strategy is deep.
limitintegerNo—Maximum number of suggestions to return (1 to 1000).
timeoutintegerNo25000Global execution timeout in milliseconds (100 to 30000).
includeGroupsbooleanNotrueWhen true, groups categorized keywords in data.groups.
noCachebooleanNofalseWhen 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 a to q 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 in data.tree.

Response

HTTP 200. A standard unified JSON response envelope:

JSON
{
  "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:

StrategySub-queries dispatchedCredits consumedUse case
normal / direct1 round1 creditReal-time search bar dropdowns
questions10 to 15 rounds3 creditsFAQ and blog content ideation
prepositions10 to 15 rounds3 creditsComparative (vs, with) search terms
intent10 to 15 rounds3 creditsHigh-intent commercial queries (best, buy)
alphabet27 rounds (A-Z)5 creditsComplete 26-letter long-tail keyword discovery
seo_matrixUp to 40 rounds8 creditsFull comprehensive SEO matrix expansion
deepHierarchicaldepth=1: 1 credit
depth=2: 4 credits
depth=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

JSON
{
  "success": false,
  "requestId": "ac_01jm9x48...",
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Insufficient credits for this request",
    "retryable": false
  }
}
HTTP statusError codeMeaning and resolution
401UNAUTHORIZEDMissing, invalid, or revoked API key. Pass a valid key in x-api-key.
402INSUFFICIENT_CREDITSAccount balance is lower than the credits required for the requested strategy. Top up in the console.
422INVALID_PARAMA parameter is missing or out of valid bounds (e.g. unknown strategy, depth > 3).
429QUOTA_EXCEEDEDRate limit exceeded. Check retryAfterMs before sending the next request.
500INTERNAL_ERRORInternal 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.