A9.com
 Search: 
Advanced Web Search
Home | Prefs | Toolbar | Sign In
Hello, sign in to enable site features.

Home > OpenSearch > OpenSearch 1.1: Description

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

Overview

OpenSearch Description files are used by search engines to describe themselves and how they can be queried (using OpenSearch Query Syntax). They are published as simple XML files over the web, and can be used by search clients to integrate third-party searches. Search results may be in the form of OpenSearch Response, another of the components of OpenSearch.

Examples

A simple OpenSearch Description file:
<?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}&amp;pw={startPage?}&amp;format=rss"/>
</OpenSearchDescription>
A detailed OpenSearch Description file:
<?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}&amp;pw={startPage}&amp;format=rss"/>
  <Url type="application/atom+xml"
       template="http://example.com/?q={searchTerms}&amp;pw={startPage?}&amp;format=atom"/>
  <Url type="text/html" 
       method="post"
       template="https://intranet/search?format=html">
    <Param name="s" value="{searchTerms}"/>
    <Param name="o" value="{startIndex?}"/>
    <Param name="c" value="{itemsPerPage?}"/>
    <Param name="l" value="{language?}"/>
  </Url>
  <LongName>Example.com Web Search</LongName>
  <Image height="64" width="64" type="image/png">http://example.com/websearch.png</Image>
  <Image height="16" width="16" type="image/vnd.microsoft.icon">http://example.com/websearch.ico</Image>
  <Query role="example" searchTerms="cat" />
  <Developer>Example.com Development Team</Developer>
  <Attribution>
    Search data &amp;copy; 2005, Example.com, Inc., All Rights Reserved
  </Attribution>
  <SyndicationRight>open</SyndicationRight>
  <AdultContent>false</AdultContent>
  <Language>en-us</Language>
  <OutputEncoding>UTF-8</OutputEncoding>
  <InputEncoding>UTF-8</InputEncoding>
</OpenSearchDescription>

MIME Type

OpenSearch Description files should be referred to via the application/opensearchdescription+xml MIME type. This MIME type is pending IANA registration.

XML Namespace

The OpenSearchDescription element and children fall under the OpenSearch 1.1 namespace: http://a9.com/-/spec/opensearch/1.1/

Extensibility

OpenSearch Descriptions can be extended via the use of standard XML 1.0 namespaces and prefixes.

For example, if Example.com wanted to inform search clients of color choices, then the OpenSearchDescription element could include an additional attribute of xmlns:example="http://example.com/opensearchextensions/1.0" and the child elements could include <example:color>Blue</example:color>.

OpenSearch Description files must not contain any elements or attributes other than those specified in this document and those in separate XML namespaces.

Elements

Required Elements:
  • OpenSearchDescription – The root node of the OpenSearch Description file.
    • The xmlns attribute must equal:
      • http://a9.com/-/spec/opensearch/1.1/
    • Note: Updated in version 1.1.
    • Requirements: Must appear exactly once.
  • ShortName – A brief name that will appear in buttons, UI controls, etc., that reference this search content provider.
    • Parent: OpenSearchDescription
    • Restrictions: Must contain 16 or fewer characters (no HTML).
    • Requirements: Must appear exactly once.
  • Description – A human readable text description of the search content provider.
    • Parent: OpenSearchDescription
    • Restrictions: Must contain 1024 or fewer characters of text (no HTML).
    • Requirements: Must appear exactly once.
  • Url – Please see the OpenSearch Query Syntax specification for documentation on the Url element, its attributes, and its contents.
    • Parent: OpenSearchDescription
    • Note: Updated in version 1.1.
    • Requirements: Must appear one or more times.
Optional Elements:
  • Contact – An email address at which the developer can be reached.
    • Parent: OpenSearchDescription
    • Note: Updated in version 1.1.
    • Restrictions: Must contain 64 or fewer characters of text (no HTML).
    • Requirements: May appear zero or one time.
  • Tags – A space-delimited set of words that are used as keywords to identify and categorize this search content.
    • Parent: OpenSearchDescription
    • Note: Updated in version 1.1.
    • Restrictions: Total length of all tags, including spaces, must contain 256 or fewer characters of text (no HTML).
    • Requirements: May appear zero or one time.
  • LongName – The name by which this search content provider is referred to in hypertext links, etc.
    • Parent: OpenSearchDescription
    • Restrictions: Must contain 48 or fewer characters of text (no HTML).
    • Default: The same value as the ShortName element.
    • Requirements: May appear zero or one time.
  • Image – A URL that identifies the location of an image that can be used in association with this search content.
    • Parent: OpenSearchDescription
    • Attributes:
      • height – height, in pixels, of this image. Optional.
      • width – width, in pixels, of this image. Optional.
      • type – the MIME-type of this image. Optional.
    • Note: Valid types correspond to those that can be displayed using the HTML <img src=""> element.
    • Note: If more than one image is available, clients will choose the most suitable for the given application, giving preference to those listed first.
    • Note: 64x64 JPEG/PNGs and 16x16 ICO files are recommended.
    • Note: Updated in version 1.1.
    • Requirements: May appear zero, one, or more times.
  • Query – used to indicate an example search; please see the OpenSearch Query specification for more information.
    • Parent: OpenSearchDescription
    • Restrictions: The role attribute must equal example.
    • Requirements: May appear zero or more times.
    • Example: <Query role="example" searchTerms="cat" />
  • Developer – The developer or maintainer of the OpenSearch feed.
    • Parent: OpenSearchDescription
    • Restrictions: Must contain 64 or fewer characters of text (no HTML).
    • Note: The Developer is not always the same as the owner, author, or copyright holder of the source of the content itself. The developer is simply the person or entity that created the feed, though they must have permission of the appropriate copyright holders.
    • Requirements: May appear zero or one time.
  • Attribution – A list of all content sources or platforms that should be credited.
    • Parent: OpenSearchDescription
    • Restrictions: Must contain 256 or fewer characters of text (no HTML).
    • Note: Please include any copyright symbols or descriptive text as desired.
    • Requirements: May appear zero or one time.
  • SyndicationRight – The degree to which the search results provided by this search engine can be distributed.
    • Parent: OpenSearchDescription
    • Values: This element must contain one of the following values (case insensitive):
      • open – search results can be published or re-published without restriction. This is the default.
      • limited – search results can be published on the client site, but not further republished.
      • private – search feed may be queried, but the results may not be displayed at the client site.
      • closed – search feed should not be queried, and will disable the column for searches.
    • Note: The SyndicationRight must be either open or limited for the content to appear on a public search aggregation site.
    • Default: "open"
    • Requirements: May appear zero or one time.
  • AdultContent – A boolean flag that must be set if the content provided is not suitable for minors
    • Parent: OpenSearchDescription
    • Values: "false", "FALSE", "0", "no", and "NO" will all be considered FALSE, all other strings will be considered TRUE
    • Default: "FALSE"
    • Requirements: May appear zero or one time.
  • Language – Indicates that the server is capable of returning results in the specified language.
    • Parent: OpenSearchDescription
    • Restrictions: Values conform those of the XML 1.0 Language Identification, as specified by RFC 3066.
    • Note: Please refer to the language parameter in the Query Syntax specification for more information on how clients can request a particular language for the search results.
    • Note: New in version 1.1.
    • Default: "*". Indicates that all languages may appear in the results.
    • Requirements: May appear zero, one, or more times.
  • OutputEncoding – Indicates that the server is capable of returning results with the specified character encoding.
    • Parent: OpenSearchDescription
    • Restrictions: Values conform those of the XML 1.0 Character Encodings, as specified by the IANA Character Set Assignments.
    • Note: Please refer to the outputEncoding parameter in the Query Syntax specification for more information on how clients can request a particular character encoding for the response.
    • Note: New in version 1.1.
    • Default: "UTF-8".
    • Requirements: May appear zero, one, or more times.
  • InputEncoding – Indicates that the server is capable of reading queries with the specified character encoding.
    • Parent: OpenSearchDescription
    • Restrictions: Values conform those of the XML 1.0 Character Encodings, as specified by the IANA Character Set Assignments.
    • Note: Please refer to the inputEncoding parameter in the Query Syntax specification for more information on how clients can indicate a particular character encoding in the request.
    • Note: New in version 1.1.
    • Default: "UTF-8".
    • Requirements: May appear zero, one, or more times.

Notes

  • Search engines should make OpenSearch Description files available via HTTP GET at a publicly accessible URL.
  • OpenSearch Description elements can contain only text; i.e., they can not contain markup such as HTML.
  • Leading and training whitespace is insignificant for any of the text elements and clients should trim the value accordingly.

Autodiscovery

Autodiscovery provides a simple means for referencing the appropriate OpenSearch Description files from a web page (HTML). It makes use of the <link> element within <head>, as described in the HTML 4.01 Specification. Autodiscovery is not a requirement of OpenSearch Description files, but it is strongly recommended so that others can find it. Below is a simple example: 

<link type="application/opensearchdescription+xml"
      rel="search" href="opensearch-description.xml">
Specification

To ensure that clients can read it, make sure to follow the HTML specification. A valid <link> tag is used, with the following restrictions:

  • The type attribute must equal application/opensearchdescription+xml. Bear in mind that this MIME type is pending IANA registration.
  • The href attribute must equal the URI of the OpenSearch Description file.
  • The rel attribute is a space-separated list of case-insensitive link types; one of these must equal search. Since search is not a link type defined in the HTML specification, include http://a9.com/-/spec/opensearch/1.1/ within the profile attribute of the <head> element, as explained in the specification.
Multiple OpenSearch Descriptions

Since a website may have more than one OpenSearch Description file, one may use more than one <link> tag. To make things easier for clients and users, using the title attribute is strongly recommended. It may, of course, also be used if there is only one <link> tag. Multiple OpenSearch Description files should be listed in order of priority. 

<link title="Book Search" type="application/opensearchdescription+xml"
      rel="search" href="osd-books.xml">
<link title="Author Search" type="application/opensearchdescription+xml"
      rel="search" href="osd-authors.xml">
XHTML Compatibility

All examples so far have shown valid HTML examples. To ensure XHTML validity, include a trailing slash: 

<link type="application/opensearchdescription+xml"
      rel="search" href="opensearch-description.xml" />

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.

[Format for printing]

Our services: A9.com Search | A9 Yellow Pages | A9.com Maps


About Us | What’s New | Media | Jobs | Feedback | Help
 Webmasters & Developers | OpenSearch

 

Conditions of Use | Privacy Policy © 2003-2006, A9.com, Inc. or its affiliates.

 

An Amazon.com Company