Version 1.0 – January 28, 2025

Table of Contents

  1. Scope
  2. Introduction
  3. Terms and Definitions
  4. Architecture Overview
  5. Endpoint
  6. Request Parameters
  7. Responses
  8. Implementation Guidelines
  9. Security Considerations
  10. Disclaimer
  11. Document History

1. Scope

This document serves as an unofficial specification for programmatically accessing Google’s Autocomplete (Google Suggest) functionality. It describes how to send requests, which parameters are accepted, and how to interpret the returned data. Since this service is not officially documented or guaranteed by Google, the described behavior may change without notice.

2. Introduction

Google’s Autocomplete / Suggest functionality provides real-time suggestions to users while they type search terms. By using the endpoint described in this specification, developers can retrieve those suggestions in either JSON or XML, depending on certain query parameters.

3. Terms and Definitions

Autocomplete / SuggestRealtime query completion suggestions offered by Google as a user types.ClientA parameter that identifies the application or interface making the request (e.g., toolbarchrome).EndpointThe base URL where requests are sent for Google Autocomplete / Suggest data.Query ParametersKey-value pairs appended to the endpoint to control aspects such as language, region, query text, or response format.JSONJavaScript Object Notation, a lightweight data-interchange format often used for asynchronous communication.XMLExtensible Markup Language, a structured data format commonly returned when client=toolbar is used.

4. Architecture Overview

The service operates via a single HTTP(S) endpoint. Clients supply query parameters in an HTTP GET request. The combination of parameters determines the language, region, output format, and other behaviors of the returned suggestions.

Important: Because this endpoint is unofficial, changes in behavior or availability may occur without any prior announcement from Google.

5. Endpoint

5.1 Base URL

The primary base endpoint for Google Autocomplete / Suggest can be accessed here:

https://suggestqueries.google.com/complete/search

All parameters are appended as standard query parameters, for example:

https://suggestqueries.google.com/complete/search?client=chrome&q=coffee

5.2 Request Method

Only HTTP GET is used for querying suggestions. The response is based on the supplied parameters.

6. Request Parameters

The following are the most commonly observed query parameters for the unofficial Google Suggest API. Some parameters impact the output format (JSON or XML), and others control localization or domain-specific suggestions (e.g., YouTube).

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.

7. Responses

7.1 JSON Format

When client=chrome or client=firefox is used, or when a JSONP callback is specified, the returned data is often a JSON array. A simplified example follows:

[
  "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.

If a callback is used (e.g. callback=myFunction), the JSON is wrapped as:

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

7.2 XML Format

When client=toolbar is used, the service often returns XML. Example:

<?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 specifying a single suggested query string.

7.3 Example Calls

JSON Example:

https://suggestqueries.google.com/complete/search?client=chrome&hl=en&q=coffee

XML Example:

https://suggestqueries.google.com/complete/search?client=toolbar&hl=en&q=coffee

8. Implementation Guidelines

8.1 Language and Market Customization

Implementers can attempt to localize suggestions by combining hl (host language) and gl (geographical location). For example:

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. However, Google may use other signals (like IP) to further localize or override settings.

8.2 Rate Limits and Throttling

There is no official information on rate limits, but excessive or abusive querying may be blocked. Best practices include:

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

8.3 Error Handling

The service may respond with unexpected status codes or data formats. Implementers should handle:

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

9. 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.

10. Disclaimer

This specification is unofficial and not endorsed by Google. The described endpoint may change or cease functioning at any time. Users of this specification assume all risks and liabilities.

11. Document History

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