Frequently Asked Questions

How do I add OpenSearch support to my site or search engine?

This section describes the technical aspects of how to add OpenSearch support your website or search engine.

Technical Spoiler: This is very technical, unless you are a 'techie' look away now to avoid overload!

OpenSearch is a standard which extends RSS to provide both a standard interface to search a web site or search engine, and a mechanism to decribe how such an interface is presented (thereby allowing semi-automatic discovery and configuration to use the interface).

The OpenSearch Description Document

The description document is used to 'self describe' the search interface provided. Its written in XML and uses the OpenSearch namespace to specify the format. It specifies information like the title of the search engine, a brief description and the actual 'search call' template to enact the search. For example:

<?xml version="1.0" encoding="UTF-8"?>
 <OpenSearchDescription xmlns=
"http://a9.com/-/spec/opensearch/1.1/">
 <ShortName>Web Search</ShortName>
 <Description>Use Example.com to search the Web.</Description>
 <Tags>example web</Tags>
 <Contact>admin@example.com</Contact>
 <Url type="application/rss+xml"
 template="http://example.com/?q={searchTerms}
&pw={startIndex?}&format=rss"/>
 </OpenSearchDescription>

For information on exactly how to format this, see http://www.opensearch.org/Specifications/
OpenSearch/1.1#OpenSearch_description_document

Important: This document you need to put in a well known & static location on your web site (for instance /osd.xml), as there is no telling how far or wide the URL refering to that file will be copied and utilised. Also do not redirect it, serve it direct from there.

The OpenSearch URL template syntax

The URL template is the 'entry point' for users wishing to search. In essence the template defines parameters to be replaced by their equivalent values (such as search terms, page to display, etc). Once the final URL is constructed, the request is made and results displayed (in our case, they fill in a search results module on the page).

A simple example would be:

http://example.com/search?q={searchTerms}

In the above, the {searchTerms} part is a parameter to be substituted with the actual search terms entered by the user (i.e. 'question Forty Two'). The standard also allows you to specify optional parameters by adding a trailing ?, as follows

http://example.com/search?q={searchTerms}&p={startIndex?}

For all the information on the range of parameters available to you, please look at http://www.opensearch.org/Specifications/
OpenSearch/1.1#OpenSearch_URL_template_syntax.

Sensible search behaviour

For people to get the best from your OpenSearch enabled search engine, we suggest you use the terms they provide in the following way:

1st: Search using the exact phrase as given. If that does not find any match..

2nd: Search by each term, total up the hits per document, and send back the hits in descreasing hit order.

This way you gracefully 'degrade' the relevance of your search results from the most specific to the most generic.

Of course if you have dedicated search engine, then you should use that, as it will deal with plurals, misspellings and word associations for you; although the above is good step in the right direction for a small site.

Advanced search support

Ideally your search engine should be sensitive to the following modifiers:

• -word A word prefixed with - means exclude all texts which exactly match this word.
• +word A word prefixed with + means include all texts which exactly match this word.
• "a phrase" A phrase enclosed in quotes means include all texts which exactly contain this phrase.

So a search for '-word +word' should return nothing matching, even if that word exists on your site.

Why should I do this? Its really a question of directly supporting acustomed behaviour by the user and making it easier for them to find exactly what they are looking for as quickly as possible. The above modifiers allow a user to quickly "zoom in" on exactly what interests them and easily filter out what they are not looking for.

How do people find this?

Once you have done all this work, its only natural to want people to use it. You have at your disposal several ways to encourage people to use your OpenSearch implementation:

1. Autodiscovery in HTML

This works by adding a link 'hint' into your html that the browser picks up and adds to its list of search engines..

You need the following bit of HTML in your home page HEAD section.

 <link rel="search"
 type="application/opensearchdescription+xml"
 href="http://example.com/osd.xml"
 title="Example Site Search" />

The sections in red you change to suit where your osd.xml file is, and what the title of your search is. The rest you copy as is and do not change.

Once this is done, and you reload the page on your favourite browser, you should notice a change to the search box.

2. Autodiscovery in RSS/Atom

If you provide a 'plain' RSS feed, this is a way of 'hinting' to the RSS Reader that you have search functionality. Depending on the favour of RSS you produce there are two ways of doing this:

RSS format

 <?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0"
 xmlns:atom="http://www.w3.org/2005/Atom">
 <channel>
 <!--- ... --->
 <atom:link rel="search"
 href="http://example.com/osd.xml"
 type="application/opensearchdescription+xml"
 title="Example Site Search" />
 <!--- ... --->
 </channel>
 </rss>

The sections in green are what you need to add into your output template. The sections in red you change to suit where your osd.xml file is, and what the title of your search is. The black text is just to give you positional context.

Atom format

 <?xml version="1.0" encoding="UTF-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom"
 xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
 <!-- ... --->
 <link rel="search"
 href="http://example.com/osd.xml"
 type="application/opensearchdescription+xml"
 title="Example Site Search" />
 <!-- ... --->
 </feed>

The sections in green are what you need to add into your output template. The sections in red you change to suit where your osd.xml file is, and what the title of your search is. The black text is just to give you positional context.

3. Set up a publically available search on Alpha (beta) and tell people

To use your OpenSearch search engine, just add it as a customise search engine that's open to all. You must use the template URL you developed above.

Return to FAQ index