Best Practices for OpenSearch

Beyond what is offered by the specification, this page provides suggestions for making sure that your OpenSearch feeds work properly, can be found, are handled properly by clients, and are easy to use for users of those clients.

Use Autodiscovery

This can’t be said enough. To help your OpenSearch feeds get found, use the autodiscovery tag; it is a single <link> tag that points to the OpenSearch Description file. Include it in your HTML web pages, in your OpenSearch Response feed, and in any other RSS or Atom feed, who’s content is searchable via your OpenSearch. See how to use it in HTML and how to use it in RSS/Atom.

OpenSearch Description Tips

Don’t mention ‘OpenSearch’ in the ShortName, LongName, Description, or Tags (unless your OpenSearch is about OpenSearch). Here is a bad description: “This searches for books by author via OpenSearch.” Use “Book search by author.” instead. Other than in Description, also avoid using the word ‘search.’

Tags is a list of keywords that describe the service. So tags such as ‘the’ and ‘and’ are pointless; remember, this is not a human-readable sentence. Tags are space-separated, so make sure you don’t separate them with commas or anything else.

You can specify more than one Image. You should probably include at least two: one 64 by 64 pixel image, and one 16 by 16 pixel image, as A9.com will use the former, and the latter is a common image size. See the specification for details.

Use the Contact element, so that you can be notified if your OpenSearch feed is broken.

Since you can specify multiple Url elements, do so. If you produce search results in HTML, RSS, Atom, or any other format – include them all.

Use example searches wisely: make sure to use a search that will always have at least some search results, and is an example that anyone can understand.

Does your search engine only handle one language? Be sure to specify it! If it can handle multiple languages, that’s great. Even better, create an OpenSearch Description file for each language your search engine supports, with the Description and other text in the appropriate language, and specifying only that language with the Language element. If you’re doing so, you can make use of the hreflang attribute for autodiscovery.

OpenSearch Response Tips

Make sure that your search engine responds to startIndex=1 or startPage=1 as beginning from the first search result. Both of these numbers are one-based, and accidentally having them zero-based is the most common mistake. You wouldn’t want clients to start showing results from the second result, or even worse, the second page of search results.

Use the OpenSearch Response elements, and atom:link elements. Those enable pagination, make it really easy for clients to understand, and even enable you to list suggested searches.

There’s nothing wrong with using HTML in search results (see Can I use HTML?), but be careful about it. HTML should only be used where necessary; CSS styling is usually not needed; Javascript should be used rarely, if ever. Note that clients may be removing any or all of the HTML, CSS, and Javascript. Lastly, there is no need to wrap the entire search result description/summary/content in a HTML element such as div, span, or p (unless required by the specification, such as div for XHTML constructs in Atom).

Overall

Make sure your OpenSearch works properly. See details on the Developer FAQ.

Tell people about it! In addition to using autodiscovery, write about it on your website where people can find it. Mention it on your ‘about’ or ‘help’ pages.