How To Return OpenSearch™ Results

The exact details on what needs to be done for your site depend on your particular technology. The OpenSearch Writers page lists software for producing OpenSearch for popular software packages, and also generic OpenSearch generating tools. There are three basic steps for publishing your search results as OpenSearch:

1. Publish the search results in OpenSearch Response format. This is essentially RSS or Atom.
   • Check to see if there is already software to do this for you.
   • If your cannot edit the source code of your search engine, you will need to find or create a wrapper application to transform the results from the existing format into OpenSearch. If the search results are already available in an XML format, XSLT may be a good choice for the transformation. If only HTML is available, you will need the wrapper to parse or scrape those results.
   • If you can edit the source code of your search engine, add OpenSearch as a new output format for the results, possibly with a URL parameter such as format=opensearch.
   • The response must be available over HTTP GET or POST, and it should support variables for basic search parameters.
   • RSS and Atom are fairly simple XML formats, and should be able to accommodate most normal search results. Note that to enable readers to request results beyond the first page, some of the optional elements are needed.
2. Create a simple OpenSearch Description file and publish on the same host as the OpenSearch Response.
3. Lastly, you’ll probably want to submit your OpenSearch to A9.com and other aggregators.

How To Indicate Errors

There is no hard rule about how errors should be communicated. However, the following pattern provides the end-user with some explanation as to what wrong, and will display properly in any reader:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/">
  <channel>
    <title>[Title]</title>
    <link>[Link]</link>
    <description>[Description]</description>
    <openSearch:totalResults>1</openSearch:totalResults>
    <openSearch:startIndex>1</openSearch:startIndex>
    <openSearch:itemsPerPage>1</openSearch:itemsPerPage>
    <item>
      <title>Error</title>
      <description>[Error message]</description>
    </item>
  </channel>
</rss>

How To Read OpenSearch Results and make OpenSearch Queries

There are a number of software libraries and other OpenSearch Readers available for reading OpenSearch. If you can’t find what you want there, you can build it yourself, as everything about OpenSearch is publicly documented. Take a look at the specification. OpenSearch Responses in RSS or Atom should be readable by any of the many publicly available parsers for those formats.

How To Discover OpenSearch Engines

Search engines that support OpenSearch should be exposing it via autodiscovery on their web pages. Additionally there is the full list of searches available on A9.com. A listing of those with the “open” syndication right are available in OpenSearch format.

Further Reading

See also the Developer FAQ, OpenSearch Tips, and of course, the OpenSearch specification.