Talk to Franz

Article

Google Autocomplete / Google Suggest Unofficial Full Specification

Google Autocomplete suggestions can be fetched with an HTTP GET request to suggestqueries.google.com/complete/search. This unofficial specification lists the parameters and the JSON and XML responses.

By Published Updated 3 min read
Google Autocomplete

Key takeaways

  • The client parameter decides the format: chrome and firefox return JSON, toolbar returns XML.
  • hl sets the language and gl the country. Google may still localize by other signals, like IP.
  • ds=yt returns YouTube suggestions instead of general Google search suggestions.
  • There is no official information on rate limits: throttle, and back off on HTTP 429 or 503.
  • Google neither documents nor guarantees the endpoint. It may change or stop working at any time.

Scope: programmatic access to Google Suggest

This unofficial specification describes how to send requests, which parameters are accepted, and how to interpret the returned data. Google does not document or guarantee the service: the behavior may change without notice.

What it returns: the suggestions users see while typing

The endpoint returns Google’s real-time suggestions in either JSON or XML, depending on certain query parameters.

Terms and Definitions

  • Autocomplete / Suggest - Realtime query completion suggestions offered by Google as a user types.
  • Client - A parameter that identifies the application or interface making the request (e.g., toolbar, chrome).
  • Endpoint - The base URL where requests are sent.
  • Query Parameters - Key-value pairs appended to the endpoint to control language, region, query text, or response format.
  • JSON - JavaScript Object Notation.
  • XML - Extensible Markup Language, commonly returned when client=toolbar is used.

Architecture: one endpoint, HTTP GET only

A single HTTP(S) endpoint, HTTP GET only. The combination of query parameters determines language, region, output format, and other behaviors.

Endpoint

Request Parameters

The most commonly observed query parameters:

ParameterExampleDescription
qq=coffeeThe query text (partial or complete) for which suggestions are requested. Must be URL-encoded when containing special characters or whitespace.
clientclient=chromeIdentifies the calling context or application. Common values include: chrome - Returns JSON formatted suggestions. toolbar - Returns XML formatted suggestions. firefox - Returns JSON, sometimes slightly different structure than Chrome.
hlhl=enThe language code (and optionally region) of the user interface. Examples: en (English), de (German), de-AT (Austrian German).
glgl=USThe 2-letter country code (ISO 3166-1 alpha-2) influencing localized results. Examples: US (United States), DE (Germany), AT (Austria).
dsds=ytDomain-specific parameter. For instance: ds=yt - YouTube suggestions. Omitting ds or using ds=web - General Google search suggestions.
jsonp or callbackjsonp=myCallbackWraps the JSON result in a JSONP callback function. E.g.: myCallback(...). Typically used to circumvent cross-domain restrictions in older JavaScript environments.

Responses

JSON Format

With client=chrome or client=firefox, or with a JSONP callback, the response is often a JSON array:

[
  "coffee",
  [
    "coffee beans",
    "coffee near me",
    "coffee table"
  ],
  [],
  {
    "google:suggesttype": ["QUERY", "QUERY", "QUERY"],
    "google:suggestrelevance": [1250, 600, 560],
    "google:verbatimrelevance": 1300
  }
]
  • The first element is the original query string ("coffee").
  • The second element is an array of suggestion strings ("coffee beans", etc.).
  • Subsequent items may contain metadata or ranking data.

With a callback (e.g. callback=myFunction), the JSON is wrapped:

myFunction(
  [
    "coffee",
    ["coffee beans", "coffee near me", ...]
  ]
)

XML Format

With client=toolbar, the service often returns XML:

<?xml version="1.0" encoding="UTF-8"?>
<toplevel>
  <CompleteSuggestion>
    <suggestion data="coffee beans"/>
  </CompleteSuggestion>
  <CompleteSuggestion>
    <suggestion data="coffee near me"/>
  </CompleteSuggestion>
</toplevel>

Each <CompleteSuggestion> block contains a <suggestion data="..."/> element with a single suggested query string.

Example Calls

Implementation Guidelines

Language and Market Customization

Combine hl (host language) and gl (geographical location) to localize suggestions:

GET https://suggestqueries.google.com/complete/search
  ?client=toolbar
  &hl=de-AT
  &gl=AT
  &q=coffee

This request tries to retrieve suggestions tailored to Austria, in Austrian German. Google may use other signals (like IP) to further localize or override settings.

Rate Limits and Throttling

No official rate limits are published, but excessive or abusive querying may be blocked.

  • Avoid sending too many requests in a short period.
  • Implement exponential backoff or retries for HTTP errors (e.g., 429 or 503).

Error Handling

The service may respond with unexpected status codes or data formats. Handle:

  • Non-200 HTTP responses.
  • Empty or truncated JSON/XML.
  • Sudden changes to the parameter or response structure.

Security Considerations

  • HTTPS: Always use https:// to encrypt traffic.
  • Privacy: Queries could be logged by Google. Adhere to relevant data protection regulations in your jurisdiction.
  • Abuse: Rapid or large-scale requests may result in IP blocking or captcha challenges.

Disclaimer

Not endorsed by Google. The endpoint may cease functioning at any time. Users of this specification assume all risks and liabilities.

Document History

  • Version 1.0 - January 28, 2025: Initial release.

All articles