Version 1.0 – January 28, 2025
Table of Contents
- Scope
- Introduction
- Terms and Definitions
- Architecture Overview
- Endpoint
- Request Parameters
- Responses
- Implementation Guidelines
- Security Considerations
- Disclaimer
- 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., toolbar
, chrome
).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).
Parameter | Example | Description |
---|---|---|
q | q=coffee | The query text (partial or complete) for which suggestions are requested. Must be URL-encoded when containing special characters or whitespace. |
client | client=chrome | Identifies 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. |
hl | hl=en | The language code (and optionally region) of the user interface. Examples: en (English), de (German), de-AT (Austrian German). |
gl | gl=US | The 2-letter country code (ISO 3166-1 alpha-2) influencing localized results. Examples: US (United States), DE (Germany), AT (Austria). |
ds | ds=yt | Domain-specific parameter. For instance:ds=yt – YouTube suggestions.Omitting ds or using ds=web – General Google search suggestions. |
jsonp or callback | jsonp=myCallback | Wraps 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.