OpenSearch

What is OpenSearch ?

OpenSearch is a collection of simple formats for the sharing of search results. The OpenSearch specification defines description document (OSDD) format that can be used to describe a search engine so that it can be used by search client applications. The OpenSearch response elements can be used to extend existing syndication formats, such as RSS and Atom, with the extra metadata needed to return search results.

Description of Service

The client uses the OSDD to learn about the public interface of the server. The OSDD contains parameterized URL templates that indicate how the search client should make search requests. The URL template can iterate as many times as the output format of the search result are supported.

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:os="http://a9.com/-/spec/opensearch/1.1/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:time="http://a9.com/-/opensearch/extensions/time/1.0/" xmlns:geo="http://a9.com/-/opensearch/extensions/geo/1.0/" xmlns:eo="http://a9.com/-/opensearch/extensions/eo/1.0/" xmlns:param="http://a9.com/-/spec/opensearch/extensions/parameters/1.0/" xmlns:dc="http://purl.org/dc/elements/1.1/">
  ...
  <description>This service is ...</description> ...
  <Url type="application/atom+xml" rel=”results” template="http://...search/atom?q={searchTerms}&ts={time:start}&te={time:end }"/>
  <Query role="example" searchTerms=”water" time:start="2012-04-01" time:end="2012-06-30”/>
  ...
</OpenSearchDescription>

Search Response

OpenSearch doesn’t define or require any specific encoding format for the search response. Instead, it defines a set of search-related metadata elements which can be inserted into existing encoding formats. Typically, list-based XML syndication formats - such as RSS 2.0 and Atom 1.0 - are used.

The OpenSearch response elements include :

totalResults number of total results
startIndex index number corresponding to the first entry item returned
itemsPerPage number of results returned
Query search query to get the same search response

Below is an example of a search response in Atom, to the free keyword “water”. Notice the three OpenSearch elements appear inside the feed element.

<feed xmlns=http://www.w3.org/2005/Atom xmlns:os=”http://a9.com/-/spec/opensearch/1.1/”>
  <title>OpenSearch response to” water”</title>
  <id>http://example.ceos.org/search?q=water</id>
  <author><name>Taro Yamada</name></author>
  <os:totalResults>231</os:totalResults>
  <os:startIndex>51</os:startIndex>
  <os:itemsPerPage>50</os:itemsPerPage>
  <os:Query role=”request” searchTerms=”water” time:start=”2012-04-01” time:end=”2012-06-30” />
  <entry>
    <title>Water Resource Management Guideline</title> <id>http://aaa.ceos.org/waterResource/guideline/v001</id>
    <link href=”http://aaa.ceos.org/waterResource/guideline/v001“/>
  </entry>
  <entry>
    ...
  </entry>
  <entry>
    ...
  </entry>
  <entry>
    ...
  </entry>
</feed>