http://www.opensearch.org/Specifications/OpenSearch/1.1
This document defines the OpenSearch description document, the OpenSearch Query element, the OpenSearch URL template syntax, and the OpenSearch response elements. Collectively these formats may be referred to as "OpenSearch 1.1" or simply "OpenSearch".
Search clients can use OpenSearch description documents to learn about the public interface of a search engine. These description documents contain parameterized URL templates that indicate how the search client should make search requests. Search engines can use the OpenSearch response elements to add search metadata to results in a variety of content formats.
The XML Namespaces URI for the XML data formats described in this specification is:
http://a9.com/-/spec/opensearch/1.1/
An OpenSearch description document can be used to describe the web interface of a search engine.
Example of a simple OpenSearch description document:
<?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={startPage?}&format=rss"/>
</OpenSearchDescription>
Example of a detailed OpenSearch description document:
<?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/atom+xml"
template="http://example.com/?q={searchTerms}&pw={startPage?}&format=atom"/>
<Url type="application/rss+xml"
template="http://example.com/?q={searchTerms}&pw={startPage?}&format=rss"/>
<Url type="text/html"
template="http://example.com/?q={searchTerms}&pw={startPage?}"/>
<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 Copyright 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>
OpenSearch description documents are referred to via the following type:
application/opensearchdescription+xml
This type is pending IANA registration.
OpenSearch description documents can be extended with foreign markup provided that all foreign elements and attributes are associated with an explicit XML namespace distinct from that of the core OpenSearch format. When possible, the foreign XML namespace URI should resolve to a document that indicates the intention and format of the extension. Clients that encounter unrecognized foreign markup should continue to process the document as if the markup did not appear.
The root node of the OpenSearch description document.
Example:
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<!--- ... --->
</OpenSearchDescription>
Contains a brief human-readable title that identifies this search engine.
Example:
<ShortName>Web Search</ShortName>
Contains a human-readable text description of the search engine.
Example:
<Description>Use Example.com to search the Web.</Description>
Describes an interface by which a client can make requests for an external resource, such as search results, search suggestions, or additional description documents.
template - The URL template to be processed according to the OpenSearch URL template syntax.
type - The MIME type of the resource being described.
rel - The role of the resource being described in relation to the description document.
indexOffset - The index number of the first search result.
pageOffset - The page number of the first set of search results.
Example of a Url element describing a request for a HTML search results page:
<Url type="text/html"
template="http://example.com/search?q={searchTerms}&pw={startPage?}" />
Example of a Url element describing a request for search results over RSS, starting with element index 0:
<Url type="application/rss+xml"
indexOffset="0"
rel="results"
template="http://example.com/?q={searchTerms}&start={startIndex?}&format=rss" />
Example of a Url element describing a request for search suggestions over JSON:
<Url type="application/json"
rel="suggestions"
template="http://example.com/suggest?q={searchTerms}" />
Example of a Url element describing a request to refresh the OpenSearch description document itself:
<Url type="application/opensearchdescription+xml"
rel="self"
template="http://example.com/osd.xml" />
Rel attribute strings can contain a space-delimited list of one or more semantically meaningful rel value tokens. An empty rel attribute value should be treated by the client as if the rel attribute was not present at all.
If a client does not recognize the semantic meaning of any rel value token, then the containing Url should be ignored by the client.
Rel value tokens may be either fully qualified tokens (e.g., "http://example.com/rel#foo") or unqualified tokens (e.g., "results").
All fully qualified tokens must be a valid URL. The semantic meaning of any fully qualified token is outside the scope of this specification, but convention dictates that the URL should resolve to a resource that describes the relationship.
All unqualified tokens must be a lowercase alphanumeric string of the form [a-z][a-z\-]+. Only those tokens listed below have meaning defined in this specification.
Rel values:
"results" (default)
"suggestions"
"self"
"collection"
Contains an email address at which the maintainer of the description document can be reached.
Example:
<Contact>admin@example.com</Contact>
Contains a set of words that are used as keywords to identify and categorize this search content. Tags must be a single word and are delimited by the space character (' ').
Example:
<Tags>example web</Tags>
Contains an extended human-readable title that identifies this search engine.
Search clients should use the value of the ShortName element if this element is not available.
Example:
<LongName>Example.com Web Search</LongName>
Contains a URL that identifies the location of an image that can be used in association with this search content.
Image sizes are offered as a hint to the search client. The search client will choose the most appropriate image for the available space and should give preference to those listed first in the OpenSearch description document. Square aspect ratios are recommended. When possible, search engines should offer a 16x16 image of type "image/x-icon" or "image/vnd.microsoft.icon" (the Microsoft ICON format) and a 64x64 image of type "image/jpeg" or "image/png".
height – Contains the height, in pixels, of this image.
width – Contains the width, in pixels, of this image.
type – Contains the the MIME type of this image.
Example:
<Image height="16" width="16" type="image/x-icon">http://example.com/favicon.ico</Image> <Image height="64" width="64" type="image/png">http://example.com/websearch.png</Image>
Defines a search query that can be performed by search clients. Please see the OpenSearch Query element specification for more information.
OpenSearch description documents should include at least one Query element of role="example" that is expected to return search results. Search clients may use this example query to validate that the search engine is working properly.
Example:
<Query role="example" searchTerms="cat" />
Contains the human-readable name or identifier of the creator or maintainer of the description document.
The developer is the person or entity that created the description document, and may or may not be the owner, author, or copyright holder of the source of the content itself.
Example:
<Developer>Example.com Development Team</Developer>
Contains a list of all sources or entities that should be credited for the content contained in the search feed.
Example:
<Attribution>Search data copyright Example.com, Inc.</Attribution>
Contains a value that indicates the degree to which the search results provided by this search engine can be queried, displayed, and redistributed.
"open" –
"limited" –
"private" –
"closed" -
Example:
<SyndicationRight>open</SyndicationRight>
Contains a boolean value that should be set to true if the search results may contain material intended only for adults.
As there are no universally applicable guidelines as to what constitutes "adult" content, the search engine should make a good faith effort to indicate when there is a possibility that search results may contain material inappropriate for all audiences.
Example:
<AdultContent>false</AdultContent>
Contains a string that indicates that the search engine supports search results in the specified language.
An OpenSearch description document should include one "Language" element for each language that the search engine supports. If the search engine also supports queries for any arbitrary language then the OpenSearch description document should include a Language element with a value of "*". The "language" template parameter in the OpenSearch URL template can be used to allow the search client to choose among the available languages.
Example:
<Language>en-us</Language> <Language>*</Language>
Contains a string that indicates that the search engine supports search requests encoded with the specified character encoding.
An OpenSearch description document should include one "InputEncoding" element for each character encoding that can be used to encode search requests. The "inputEncoding" template parameter in the OpenSearch URL template can be used to require the search client to identify which encoding is being used to encode the current search request.
Example:
<InputEncoding>UTF-8</InputEncoding>
Contains a string that indicates that the search engine supports search responses encoded with the specified character encoding.
An OpenSearch description document should include one "OutputEncoding" element for each character encoding that can be used to encode search responses. The "outputEncoding" template parameter in the OpenSearch URL template can be used to allow the search client to choose a character encoding in the search response.
Example:
<OutputEncoding>UTF-8</OutputEncoding>
Search engines that publish OpenSearch description documents can assist search clients in the discovery of OpenSearch interfaces through the use of "link" elements. Search engines that support OpenSearch should include a reference to the related OpenSearch description document on each page of search results.
RSS and Atom documents may reference related OpenSearch description documents via the Atom 1.0 "link" element, as specified in Section 4.2.7 of RFC 4287.
The "rel" attribute of the link element should contain the value "search" when referring to OpenSearch description documents. This relationship value is pending IANA registration. The reuse of the Atom link element is recommended in the context of other syndication formats that do natively support comparable functionality.
The following restrictions apply:
Example of Atom-based search results that include an OpenSearch autodiscovery link element:
<?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/opensearchdescription.xml"
type="application/opensearchdescription+xml"
title="Content Search" />
<!-- ... --->
</feed>
Example of RSS-based search results that include an OpenSearch autodiscovery link element:
<?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/opensearchdescription.xml"
type="application/opensearchdescription+xml"
title="Content Search" />
<!--- ... --->
</channel>
</rss>
HTML and XHTML documents may reference related OpenSearch description documents via the HTML 4.0 <link/> element.
The following restrictions apply:
Example of an HTML document that includes OpenSearch autodiscovery link elements:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head profile="http://a9.com/-/spec/opensearch/1.1/">
<!--- ... --->
<link rel="search"
type="application/opensearchdescription+xml"
href="http://example.com/content-search.xml"
title="Content search" />
<link rel="search"
type="application/opensearchdescription+xml"
href="http://example.com/comment-search.xml"
title="Comments search" />
<!--- ... --->
</head>
<body>
<!--- ... --->
</body>
</html>
For the purposes of RFC 4288 section 4.10 this specification contains the registration template for MIME type application/opensearchdescription+xml. This type is pending IANA registration.
Type name: application
Subtype name: opensearchdescription+xml
Required parameters:
There are no required parameters.
Optional parameters:
charset (defaults to "UTF-8")
Encoding considerations:
Identical to those of "application/xml" as described
in RFC 3023; especially "UTF-8" (RFC 3629) and its
proper subset "US-ASCII" are supposed to work.
For non-ASCII documents served as "text/xml" the
"charset" parameter is required; this might be
relevant when authors are unable to configure the
server hosting their OSD (OpenSearch Description
document).
Security considerations:
All general security and privacy considerations for
sending queries to servers specified in an URL are
applicable.
Where clients support the optional update feature in
OSDs it affects the privacy of users.
The Ecmascript API AddSearchProvider() typically
enforces a "same origin" policy for the OSD; the URL
element within the OSD can designate a third party
as search provider.
An OSD can claim to be a search description for X,
but actually do something else.
Interoperability considerations:
OSDs use the <http://a9.com/-/spec/opensearch/1.1/>
XML name space, optionally in conjunction with other
XML name spaces for extensions or application specific
purposes.
Published specification:
<http://www.opensearch.org/Specifications/OpenSearch/1.1>
Applications that use this media type:
Various Web browsers, search engines, and software
libraries support OSDs. The "search" link relation
is used on many Web pages with this media type.
The Ecmascript API AddSearchProvider() documented for
WhatWG HTML uses this media type.
Additional information:
OSDs have no "magic numbers" as defined in RFC 4288.
There are no special "common file name extensions" for
OSDs, OSDs are XML documents. If specific extensions
are desired the conventional ".osdx" or ".a9.xml" might
do the trick.
Person & email address to contact for further information:
<http://groups.google.com/group/opensearch>
<http://www.opensearch.org/Community/Guidelines>
Intended usage: COMMON
Restrictions on usage:
None
Author: DeWitt Clinton
Change controller:
<http://www.opensearch.org/>
The OpenSearch URL template format can be used to represent a parameterized form of the URL by which a search engine is queried.
The search client will process the URL template and attempt to replace each instance of a template parameter, generally represented in the form {name}, with a value determined at query time.
By default, parameter names are considered part of the OpenSearch 1.1 template namespace, and definitions for a set of core search parameter names are provided in this specification. However, search engines and search clients can adopt new parameter names using an extensibility mechanism based on the XML namespace prefix conventions.
Example of a search URL template that contains a template parameter:
http://example.com/search?q={searchTerms}
Example of a search URL template that contains an optional template parameter:
http://example.com/feed/{startPage?}
Example of a search URL template that contains an optional template parameter in an extended namespace, shown in the context of a Url element:
<Url type="application/rss+xml"
xmlns:example="http://example.com/opensearchextensions/1.0/"
template="http://example.com?q={searchTerms}&c={example:color?}"/>
This specification refers to the use of the OpenSearch URL template syntax specifically within the context of the "Url" element in an OpenSearch description document.
The grammar of an OpenSearch URL template is defined by the following set of ABNF rules, as specified in RFC 2234.
The grammar rules defined in this document build upon a subset of the rules defined for the Uniform Resource Identifier (URI): Generic Syntax in RFC 3986. For brevity, rules already stated in RFC 3986 are referenced in this document by rule name alone and are not restated here in their entirety.
ttemplate = tscheme ":" thier-part [ "?" tquery ] [ "#" tfragment ]
tscheme = *( scheme / tparameter )
thier-part = "//" tauthority ( tpath-abempty / tpath-absolute / tpath-rootless / path-empty )
tauthority = [ tuserinfo "@" ] thost [ ":" tport ]
tuserinfo = *( userinfo / tparameter )
thost = *( host / tparameter )
tport = *( port / tparameter )
tpath-abempty = *( "/" tsegment )
tsegment = *( segment / tparameter )
tpath-absolute = "/" [ tsegment-nz *( "/" tsegment ) ]
tsegment-nz = *( segment-nz / tparameter )
tpath-rootless = tsegment-nz *( "/" tsegment )
tparameter = "{" tqname [ tmodifier ] "}"
tqname = [ tprefix ":" ] tlname
tprefix = *pchar
tlname = *pchar
tmodifier = "?"
tquery = *( query / tparameter )
tfragement = *( fragement / tparameter )
The search client must replace every instance of a template parameter with a value before the search request is performed.
If a search engine wishes to indicate that a template parameter is optional and can be replaced with the empty string, then the "?" notation described in the section on optional template parameters should be used.
A parameter name consists of an optional parameter name prefix followed by the local parameter name. If the parameter name prefix is present then it will be separated from the local parameter name with the ":" character. All parameter names are associated with a parameter namespace. In the case of unqualified parameter names, the local parameter name is implicitly associated with the OpenSearch 1.1 namespace. In the case of fully qualified parameter names, the local parameter name is explicitly associated with an external namespace via the parameter name prefix.
Both the parameter name prefix and the local parameter name are case sensitive.
A parameter name prefix associates a local parameter name with a parameter namespace. All parameter name prefixes must be previously declared as an XML namespace prefix on the containing element or ancestor elements.
The choice of prefix is at the discretion of the author of the OpenSearch description document. Search clients should make no assumption as to the meaning of any particular literal prefix string, and should rely exclusively on the mapping of prefix strings to XML namespace declarations when parsing fully qualified parameter names.
Example of two equivalent URL templates that will be processed identically by search clients:
<Url type="application/rss+xml"
xmlns:a="http://example.com/extensions/"
template="http://example.com?q={a:localname?}"/>
<Url type="application/rss+xml"
xmlns:b="http://example.com/extensions/"
template="http://example.com?q={b:localname?}"/>
Unqualified parameter names consist of only a local parameter name and do not include a parameter name prefix. Unqualified parameter names in OpenSearch URL templates are implicitly associated with the OpenSearch 1.1 namespace.
This specification includes an exhaustive list of all unqualified OpenSearch 1.1 parameter names.
Example of an unqualified parameter name:
<Url type="application/rss+xml"
template="http://example.com/?q={searchTerms}"/>
Fully qualified parameter names consist of a parameter name prefix, followed by the ":" character, followed by the local parameter name. Fully qualified parameter names are associated with the namespace identified by the paramater name prefix, as it appears as an XML namespace declaration on the containing element or ancestor elements.
Example of a fully qualified parameter name:
<Url type="application/rss+xml"
xmlns:example="http://example.com/opensearchextensions/1.0/"
template="http://example.com?f={example:format?}"/>
Required template parameters are template parameters that do not contain a template parameter modifier. The search client may use the default value if one is known, but may not use the empty string as a value.
Example of a required template parameter:
{searchTerms}
Optional template parameters are template parameters that contain a template parameter modifier equal to "?". The search client may use the empty string as a value if no other value is available.
Example of an optional template parameter:
{startPage?}
The following local parameter names are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the local parameter names listed below may appear unqualified in an OpenSearch URL template.
Search clients should be prepared to substitute reasonable values for these parameter names when they appear in an OpenSearch URL template.
Replaced with the keyword or keywords desired by the search client.
Replaced with the number of search results per page desired by the search client.
Search clients should anticipate that the value of the "count" parameter may not be honored by the search engine, and should rely exclusively on the contents of the "itemsPerPage" response element in calculating actual page size.
Replaced with the index of the first search result desired by the search client.
Replaced with the page number of the set of search results desired by the search client.
Replaced with a string that indicates that the search client desires search results in the specified language.
An OpenSearch description document should include one "Language" element for each language that the search engine supports. If the search engine also supports queries for any arbitrary language then the OpenSearch description document should include a Language element with a value of "*". The "language" template parameter in the OpenSearch URL template can be used to allow the search client to choose among the available languages.
Replaced with a string that indicates that the search client is performing the search request encoded with the specified character encoding.
An OpenSearch description document should include one "InputEncoding" element for each character encoding that can be used to encode search requests. The "inputEncoding" template parameter in the OpenSearch URL template can be used to require the search client to identify which encoding is being used to encode the current search request.
Replaced with a string that indicates that the search client desires a search response encoding with the specified character encoding.
An OpenSearch description document should include one "OutputEncoding" element for each character encoding that can be used to encode search responses. The "outputEncoding" template parameter in the OpenSearch URL template can be used to allow the search client to choose a character encoding in the search response.
The OpenSearch Query element can be used to define a specific search request that can be performed by a search client.
The Query element attributes correspond to the search parameters in a URL template. The core set of search parameters are explicitly defined as Query attributes, and custom parameters can be added via namespaces as needed.
Authors should provide at least one Query element of role="example" in each OpenSearch description document so that search clients can test the search engine. Search engines should include a Query element of role="request" in each search response so that search clients can recreate the current search.
Example of a Query element used in an OpenSearch description document to provide an example search request for search clients:
<Query role="example" searchTerms="cat" />
Example of a Query element used in an OpenSearch response to echo back the original search request:
<Query role="request" searchTerms="cat" startPage="1" />
Example of a Query element used in an OpenSearch response to correct the spelling of "OpenSurch":
<Query role="correction" searchTerms="OpenSearch" totalResults="854000" title="Spelling correction" />
Example of a Query element using an extended parameter:
<Query xmlns:custom="http://example.com/opensearchextensions/1.0/"
role="example"
searchTerms="cat"
custom:color="blue"
title="Sample search" />
Example of a Query element using a extended role:
<Query xmlns:custom="http://example.com/opensearchextensions/1.0/"
role="custom:synonym"
title="Synonym of 'cat'"
searchTerms="feline" />
Detailed example of a set of Query elements used in the context of an Atom-based OpenSearch response:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
<!--- ... --->
<opensearch:Query role="request" searchTerms="General Motors annual report" />
<opensearch:Query role="related" searchTerms="GM" title="General Motors stock symbol" />
<opensearch:Query role="related" searchTerms="automotive industry revenue" />
<opensearch:Query role="subset" searchTerms="General Motors annual report 2005"
<opensearch:Query role="superset" searchTerms="General Motors" />
<!-- ... -->
</feed>
Describes a specific search request that can be made by the search client.
role - Contains a string identifying how the search client should interpret the search request defined by this Query element.
title - Contains a human-readable plain text string describing the search request.
totalResults - Contains the expected number of results to be found if the search request were made.
searchTerms - Contains the value representing the "searchTerms" as an OpenSearch 1.1 parameter.
count - Contains the value representing the "count" as a OpenSearch 1.1 parameter.
startIndex - Contains the value representing the "startIndex" as an OpenSearch 1.1 parameter.
startPage - Contains the value representing the "startPage" as an OpenSearch 1.1 parameter.
language - Contains the value representing the "language" as an OpenSearch 1.1 parameter.
inputEncoding - Contains the value representing the "inputEncoding" as an OpenSearch 1.1 parameter.
outputEncoding - Contains the value representing the "outputEncoding" as an OpenSearch 1.1 parameter.
Example:
<Query role="example" searchTerms="cat" />
The Query element may contain additional attributes if the extended attributes are associated with a namespace. Search clients should interpret extended attributes to represent the corresponding template parameter by the same name in the specified namespace.
Example of a Query element representing a search request that contains an extended attribute that corresponds to an extended search parameter:
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
xmlns:custom="http://example.com/opensearchextensions/1.0/">
<Url type="text/html"
template="http://example.com/search?color={custom:color?}" />
<Query role="example" custom:color="blue" />
<!-- ... -->
</OpenSearchDescription>
A role value consists of an optional prefix followed by the local role value. If the prefix is present it will be separated from the local role value with the ":" character. All role values are associated with a namespace, either implicitly in the case of local role values, or explicitly via a prefix in the case of fully qualified role values.
The role attribute may take on values beyond those specified in this document provided they are fully qualified with a prefix and associated with a declared namespace. Clients that encounter unrecognized role values should continue to process the document as if the Query element containing the unrecognized role value did not appear.
A role prefix associates a local role name with a namespace. All prefixes must be previously declared as an XML namespace prefix on the containing Query element or ancestor elements.
Local role values are not preceded by a prefix. Local role values are associated with the OpenSearch 1.1 namespace.
The following role values are identified with the OpenSearch 1.1 namespace. The list is exhaustive; only the role values listed below may appear in the OpenSearch 1.1 namespace.
Role values:
"request"
"example"
"related"
"correction"
"subset"
"superset"
Example of a local role value:
<Query role="related"
title="A related search"
searchTerms="tiger" />
Fully qualified role values are preceded by a prefix. Fully qualified role values are associated with the namespace identified by the prefix on the containing Query element or ancestor elements.
Example of a fully qualified role value:
<Query xmlns:custom="http://example.com/opensearchextensions/1.0/"
role="custom:synonym"
title="Synonyms of 'cat'"
searchTerms="feline" />
The OpenSearch response elements can be used by search engines to augment existing XML formats with search-related metadata.
OpenSearch response elements are typically found augmenting search results returned in list-based XML syndication formats, such as RSS 2.0 and Atom 1.0, but may be used in other contexts without restriction.
Example of a page of search results in the RSS 2.0 format:
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:atom="http://www.w3.org/2005/Atom">
<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>
<atom:link rel="search" type="application/opensearchdescription+xml" href="http://example.com/opensearchdescription.xml"/>
<opensearch:Query role="request" searchTerms="New York History" startPage="1" />
<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>
</channel>
</rss>
Example of a page of search results in the Atom 1.0 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/">
<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:Query role="request" searchTerms="New York History" startPage="1" />
<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&format=atom" type="application/atom+xml"/>
<link rel="first" href="http://example.com/New+York+History?pw=1&format=atom" type="application/atom+xml"/>
<link rel="previous" href="http://example.com/New+York+History?pw=2&format=atom" type="application/atom+xml"/>
<link rel="next" href="http://example.com/New+York+History?pw=4&format=atom" type="application/atom+xml"/>
<link rel="last" href="http://example.com/New+York+History?pw=42299&format=atom" type="application/atom+xml"/>
<link rel="search" type="application/opensearchdescription+xml" href="http://example.com/opensearchdescription.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>
</feed>
The number of search results available for the current search.
If the totalResults element does not appear on the page then the search client should consider the current page to be the last page of search results.
Example:
<totalResults>492420</totalResults>
The index of the first search result in the current set of search results.
If the startIndex element does not appear on the page then the search client should consider the current page to be the first page of search results.
Example:
<startIndex>11</startIndex>
The number of search results returned per page.
If the itemsPerPage element does not appear on the page then the search client should use the number of items of the current page as the default page size.
Example:
<itemsPerPage>10</itemsPerPage>
Defines a search query that can be performed by search clients. Please see the OpenSearch Query element specification for more information.
Search results should include a Query element of type="request" that can be used to recreate the search request that generate the current search response.
Example:
<Query role="request" searchTerms="cat" />
OpenSearch response metadata may be included in well-formed HTML/XHTML via the HTML 4.0.1 "meta" element.
The following meta element "name" attribute values are recognized under the profile associated with the OpenSearch 1.1 namespace:
"totalResults" - Corresponds to value of the "totalResults" element.
"startIndex" - Corresponds to value of the "startIndex" element.
"itemsPerPage" - Corresponds to value of the "itemsPerPage" element.
Example of a page of search results in the XHTML 1.0 format:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head profile="http://a9.com/-/spec/opensearch/1.1/" >
<title>Example.com Search: New York history</title>
<link rel="search"
type="application/opensearchdescription+xml"
href="http://example.com/opensearchdescription.xml"
title="Example.com Web Search" />
<meta name="totalResults" content="4230000"/>
<meta name="startIndex" content"1"/>
<meta name="itemsPerPage" content="10"/>
</head>
<body>
<ul>
<li>
<a href="http://www.columbia.edu/cu/lweb/eguids/amerihist/nyc.html">
New York History
</a>
<div>
... 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. ...
</div>
</li>
<!-- ... -->
</ul>
</body>
</html>
DeWitt Clinton <dewitt@opensearch.org>
Joel Tesler <tesler@a9.com>, Michael Fagan <mifa@a9.com>, Joe Gregorio <joe@bitworking.org>, Aaron Sauve <aaronsa@microsoft.com>, James Snell <jasnell@us.ibm.com>
This document is made available by A9.com subject to the terms of the Creative Commons Attribution-ShareAlike 2.5 License.