google-autocomplete-api

Google Autocomplete API

The suggestions Google offers while a query is being typed, as JSON. Useful for keyword research, for query expansion, and for seeing what Google thinks a partial phrase is heading towards.

Endpoint

One credit per request. Send the partial query as q; the response is the dropdown Google would have shown, in order.

GET/v1/autocomplete

bash

curl -G "https://api.serpix.io/v1/autocomplete" \
  --data-urlencode "q=how to make ch" \
  -H "Authorization: Bearer $SERPIX_API_KEY"

The same parameters are accepted as a JSON body on POST /v1/autocomplete:

post variant

curl -X POST "https://api.serpix.io/v1/autocomplete" \
  -H "Authorization: Bearer $SERPIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "how to make ch"}'

Parameters

Query
field	type	default	description
qrequired	string	–	The partial query to complete.
cp	integer	–	Cursor position within `q`, when completing mid-phrase rather than at the end.

Surface and locale

Surface and locale
field	type	default	description
client	string	chrome	Which Google surface to ask as. Different clients return differently shaped dropdowns, because Chrome's omnibox, the mobile app and the web box do not suggest identically.
gl	string	–	Country to suggest for, two-letter code. Defaults to `us`.
hl	string	en	Language of the suggestions, two-letter code.

Unknown parameters are never silently ignored. A request carrying one is rejected with 422 before anything runs, so a typo can't bill you for results you didn't ask for. Common parameters from raw Google URLs and other SERP APIs get a pointed message naming the equivalent here:

Rejected aliases
field	type	default	description
ds	422	–	Chosen by `client`: youtube, img and products-cc address their own vertical for you.
num	422	–	Google decides how many suggestions each client serves.
keyword	422	–	Use `q`.
cursor_pointer	422	–	Use `cp`.
location / uule / lat / lon	422	–	Suggestions localize by `gl` and `hl`.
device	422	–	Each `client` is one suggest surface; there is no device variant.
google_domain	422	–	Suggestions are served from google.com in every locale; pick the locale with `gl` and `hl`.
xssi	422	–	Not needed. Responses are parsed for you.
callback / jsonp	422	–	Not supported. Responses are plain JSON.
engine	422	–	Not needed. This endpoint is Google Autocomplete.
api_key	422	–	Authenticate with the `Authorization` header, never the query string.

422 · rejected parameter

HTTP/2 422
content-type: application/json

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query"],
      "msg": "Value error, `ds` is not supported: chosen by `client` — youtube, img and products-cc address their own vertical for you",
      "input": { "q": "how to make ch", "ds": "yt", ... }
    }
  ]
}

Response

A request returns one JSON object: two envelope objects that are always present (search_metadata, search_parameters), the dropdown as suggestions, and verbatim_relevance. A field that wasn't served is omitted entirely, never null, never [], so a presence check is all you need before reading one.

200 · trimmed

{
  "search_metadata": {
    "id": "srx_5SIKB8BtevtpZzrr",
    "status": "success",
    "created_at": "2026-07-28T18:57:48Z",
    "took_ms": 455,
    "parser_version": "2026.07.1",
    "google_url": "https://www.google.com/complete/search?client=chrome&q=how+to+make+ch&hl=en&gl=us",
    "html_url": "https://api.serpix.io/searches/srx_5SIKB8BtevtpZzrr/bHOhaozWIL74pWpm.html",
    "json_url": "https://api.serpix.io/searches/srx_5SIKB8BtevtpZzrr/bHOhaozWIL74pWpm.json"
  },
  "search_parameters": {
    "q": "how to make ch",
    "client": "chrome",
    "gl": "us",
    "hl": "en"
  },
  "suggestions": [
    { "position": 1, "value": "how to make chicken salad", "relevance": 601, "type": "query" },
    { "position": 2, "value": "how to make chimichurri", "relevance": 600, "type": "query" },
    { "position": 3, "value": "how to make chocolate chip cookies", "relevance": 562, "type": "query" },
    { "position": 4, "value": "how to make cheese", "relevance": 561, "type": "query" },
    ...
  ],
  "verbatim_relevance": 851
}

Every response also reports its cost in the X-Serpix-Credits-Charged and X-Serpix-Credits-Remaining headers.

search_metadata

search_metadata fields
field	type	default	description
id	string	–	Unique id of this request, `srx_` prefixed.
status	string	–	`success` on every 200.
created_at	string	–	When the request ran, ISO 8601 UTC.
took_ms	integer	–	End-to-end time to serve this response, in milliseconds.
parser_version	string	–	Dated version of the autocomplete parser that produced this response, so any response can be tied to the parsing behaviour that made it. Each vertical carries its own.
google_url	string	–	The exact Google URL fetched.
html_url	string	–	Archived copy of Google's own response. Included when available.
json_url	string	–	Archived copy of this JSON response. Included when available.

search_parameters

The parameters the request actually ran with, defaults filled in.

search_parameters fields
field	type	default	description
q	string	–	The partial query as received.
client	string	–	Suggest surface used.
gl	string	–	Country suggested for.
hl	string	–	Language used.
cp	integer	–	Cursor position used. Present when sent.

suggestions

Each suggestion carries a relevance score, which is Google's own ranking weight rather than anything we compute. Higher means Google ranked it above its neighbour.

suggestions entry fields
field	type	default	description
position	integer	–	Rank in the dropdown, starting at 1.
value	string	–	The suggested query, exactly as Google would display it.
relevance	integer	–	Google's own ranking weight for the suggestion.
type	string	–	What kind of suggestion it is. Usually `query`, but Google also suggests ENTITIES, and those carry the four fields below.
title	string	–	Entity suggestions only: the entity's name.
subtitle	string	–	Entity suggestions only: Google's one-line description, like `American singer-songwriter`.
thumbnail	string	–	Entity suggestions only: a picture of the entity.
entity_id	string	–	Entity suggestions only: Google's knowledge identifier for it.

A plain-query suggestion carries only the first four fields. The sample above is all queries, which is the common case; ask about a person or a place and Google mixes in entity suggestions that fill the rest. verbatim_relevance is the weight Google gives the query as actually typed, against which the suggestions compete.

Errors

A rejected request answers with detail, naming the parameter and what to send in its place. A request that could not be completed answers with error and a search_id you can quote. No error is ever charged.

Status codes
field	type	default	description
401	unauthorized	−0	Missing, malformed, or revoked key. See Authentication.
402	payment required	−0	The balance can't cover a request. See Credits & billing.
422	invalid request	−0	Unknown or invalid parameter. The `detail` names the parameter and what to send in its place.
502	search_failed	−0	The request could not be completed. Retry it; you were not charged.
503	search_unavailable	−0	Google did not serve a usable response. Retry it; you were not charged.

502 · search failed

HTTP/2 502
content-type: application/json
x-serpix-credits-charged: 0

{ "error": { "code": "search_failed", "search_id": "srx_kq3v9tR2xLw8mA1c" } }