Home » Specifications » OpenSearch » Extensions » Suggestions » 1.0



This is a draft document for public review.


The OpenSearch Suggestions extension offers a convention by which search engines can return a set of search term completions for a given search prefix. The search completions can be used by a search client to dynamically present the end user with search term suggestions.


The Google Suggest project pioneered a mechanism for dynamically presenting a list of search term completions as the user interacts with the search interface. The Firefox web browser incorporates this technique into the browser search box to offer the user dynamic search term suggestions. This document is based on the Firefox Search Service design documentation.


The following type is used to indicate that the response will contain search suggestions:


OpenSearch Description document

Search engines that support search suggestions can use the OpenSearch Description document to publish URL templates for the search query.

URL elements

Url elements of type="application/x-suggestions+json" should be used by the client to retrieve search suggestions.


 <?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
   <Url type="text/html"
   <Url type="application/x-suggestions+json"
   <!-- ... -->

Search Suggestions Response

Response Format

The response body should be returned in JavaScript Object Notation as a JavaScript array of arrays.

Response Content

Search suggestions are returned as an ordered collection of values. The four values are returned in the following order:

  • Query String
  • Completions
  • Descriptions
  • Query URLs

Query String

Description: A single element echoing the requested search term. The search client may validate that this value matches the expected response.

Required: yes




Description: A list of suggested completions for the given search term.

Required: yes


 "sears","search engines","search engine","search","sears.com","seattle times"


Description: A list of human-readable strings that provide additional information or context regarding the suggested completion.

Required: no


 "7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"

Query URLs

Description: A list of URLs that should be used by the search client to request the suggested search term at the corresponding position in the completions lists.

Required: no




The following is a full example of a JSON formatted search suggestions response:

 ["sea",["sears","search engines","search engine","search","sears.com","seattle times"],["7,390,000 results","17,900,000 results","25,700,000 results","1,220,000,000 results","1 result","17,600,000 results"],["http://example.com?q=sears","http://example.com?q=search+engines","http://example.com?q=search+engine","http://example.com?q=search","http://example.com?q=sears.com","http://example.com?q=seattle+times"]]


Extension documentation written up by DeWitt Clinton <dewitt@opensearch.org>, based directly on the work of Joe Hughes' Firefox search suggestions draft documentation and the Google search suggestions format.


This document is made available by A9.com subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License.