Home » Specifications » OpenSearch » Extensions » Suggestions » 1.0

Contents

Notice

This is a draft document for public review.

Introduction

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.

Background

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.

Type

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

application/x-suggestions+json

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.

Example

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

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

Example:

 "sea"

Completions

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

Required: yes

Example:

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

Descriptions

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

Required: no

Example:

 "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

Example:

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


Example

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"]]

Authors

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.

License

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