Note: This is Draft 2 of the 1.1 specification, and changes may be made before the final version.

Overview

OpenSearch™ Response elements are used to add search data to existing XML-based syndication formats, such as RSS 2.0 and Atom 1.0. These extensions are designed to work with OpenSearch Description files, another of the components of OpenSearch, to provide rich search syndication with a minimal amount of overhead.

OpenSearch Response introduces several elements that provide the necessary information for syndicating search results. Additionally, OpenSearch Response recommends clean extensibility guidelines, and suggests that clients and servers recognize certain other common extensions to enhance search results.

On This Page

• Examples
  • RSS 2.0
  • Atom 1.0
• XML Namespace
• Elements
  • totalResults
  • startIndex
  • itemsPerPage
  • link
  • Query
• Extensibility
• Recommended Extensions
  • Atom links
• License

Examples

Simple search results, using RSS 2.0 and the OpenSearch Response extensions.

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" 
     xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <channel>
    <title>Example.com Search: New York history</title>
    <link>http://example.com/New+York+history</link>
    <description>Search results for "New York history" at Example.com</description>
    <opensearch:totalResults>4230000</opensearch:totalResults>
    <opensearch:startIndex>21</opensearch:startIndex>
    <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
    <opensearch:link rel="search"
                     href="http://example.com/opensearchdescription.xml" type="application/opensearchdescription+xml"/>
    <opensearch:Query role="request" searchTerms="New York History" />
    <item>
      <title>New York History</title>
      <link>http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html</link>
      <description>
        ... Harlem.NYC - A virtual tour and information on 
        businesses ...  with historic photos of Columbia's own New York 
        neighborhood ... Internet Resources for the City's History. ...
      </description>
    </item>
    <!-- 9 additional <item> elements appear here -->
  </channel>
</rss>

The same simple search results, using Atom 1.0 and the OpenSearch Response extensions.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" 
      xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>Example.com Search: New York history</title> 
  <link href="http://example.com/New+York+history"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author> 
    <name>Example.com, Inc.</name>
  </author> 
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
  <opensearch:totalResults>4230000</opensearch:totalResults>
  <opensearch:startIndex>21</opensearch:startIndex>
  <opensearch:itemsPerPage>10</opensearch:itemsPerPage>
  <opensearch:link rel="search"
                   href="http://example.com/opensearchdescription.xml" type="application/opensearchdescription+xml"/>
  <opensearch:Query rel="request" searchTerms="New York History" />
  <link rel="alternate" href="http://example.com/New+York+History?pw=3" type="text/html"/>
  <link rel="self" href="http://example.com/New+York+History?pw=3&amp;format=atom" type="application/atom+xml"/>
  <link rel="first" href="http://example.com/New+York+History?pw=1&amp;format=atom" type="application/atom+xml"/>
  <link rel="previous" href="http://example.com/New+York+History?pw=2&amp;format=atom" type="application/atom+xml"/>
  <link rel="next" href="http://example.com/New+York+History?pw=4&amp;format=atom" type="application/atom+xml"/>
  <link rel="last" href="http://example.com/New+York+History?pw=42299&amp;format=atom" type="application/atom+xml"/>
  <entry>
    <title>New York History</title>
    <link href="http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <content type="text">
      ... Harlem.NYC - A virtual tour and information on 
      businesses ...  with historic photos of Columbia's own New York 
      neighborhood ... Internet Resources for the City's History. ...
    </content>
  </entry>
  <!-- 9 additional <entry> elements appear here -->  
</feed>

XML Namespace

The OpenSearch Response elements fall under the OpenSearch 1.1 namespace: http://a9.com/-/spec/opensearch/1.1/

Elements

The OpenSearch Response extension aims to define the bare minimum of additional functionality required to provide search results over syndication channels.

The following elements can be added to existing XML-based syndication formats. In the case of RSS 2.0, these elements are added as children to the <channel> element. In the case of Atom 1.0, these elements are added as children to the <feed> element.

• totalResults – the maximum number of results available for these search terms
  • Restrictions: An integer greater than or equal to 0.
  • Default: The number of items that were returned in this set of results.
  • Requirements: May appear zero or one time.
• startIndex – the index of the first item returned in the result.
  • Restrictions: An integer greater than or equal to 1.
  • Note: The first result is 1.
  • Default: 1
  • Requirements: May appear zero or one time.
• itemsPerPage – the maximum number of items that can appear in one page of results.
  • Restrictions: An integer greater than or equal to 1.
  • Default: The number of items that were returned in this set of results.
  • Requirements: May appear zero or one time.
• link – a reference back to the OpenSearch Description file
  • Attributes: This is a clone of the link element in Atom, including href, hreflang, rel, and type attributes.
  • Restrictions: The rel attribute must equal search.
  • Note: New in version 1.1.
  • Requirements: May appear zero or one time.
• Query – in an OpenSearch Response, can be used both to echo back the original query and to suggest new searches. Please see the OpenSearch Query specification for more information.
  • Note: New in version 1.1.
  • Requirements: May appear zero or more times. Note that the “Q” is capitalized.

Extensibility

The OpenSearch Response format can be extended via the use of standard XML 1.0 namespaces and prefixes.

For example, if Example.com wanted to inform clients of the "color" of a particular search result, then the root element of the result set would include an namespace declaration of xmlns:example="http://example.com/opensearchextensions/1.0" and each item could contain <example:color>Blue</example:color>.

Recommended Extensions

In order to provide a consistent representation of search result data, certain common extensions are recommended. In particular, the following are recommended:

• Atom’s link element is used to indicate inter-document relationships. Suggested links include those with the rel attribute values of alternate, self, first, previous, next, and last, which are demonstrated in the Atom example.

License

All components of the OpenSearch 1.1 specification are made available by A9.com subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License (the License). The License applies only to the OpenSearch specification, and not to any other technology or copyrightable works of A9.com or its affiliates.